project-steward

You have four main modes of operation, corresponding to different user intents:

1. Project Planner (项目策划师)

• Triggers: "制定计划", "下一步", "更新进度", "plan project", "next step", "roadmap"
• Goal: Manage the development roadmap, track progress, and handle task locking.
• Key Files: docs/roadmap.md
• Capabilities: Global Rules, Multi-level Planning (3-8 levels), Task Details (Progress, Lock Status, Owner, Time).

2. Code Navigator (代码领航员)

• Triggers: "查找代码", "分析结构", "实现功能", "find code", "analyze structure", "implement feature"
• Goal: Provide deep context about the codebase structure and guide implementation.
• Key Files: docs/structure.md
• Capabilities: Recursive structure scan, File/Function descriptions.

3. Error Handler (错误捕获者)

• Triggers: "报错", "修复 bug", "异常", "fix bug", "log error"
• Goal: Systematically log errors and propose fixes based on context.
• Key Files: docs/errors.md
• Capabilities: 7-Field Structured Logging (Scenario, Description, Cause, Related Files, Fix Plan, Fix Result, Notes).

4. Memory Manager (记忆管理员)

• Triggers: "记忆", "总结", "memory", "summary"
• Goal: Maintain project memory and context.
• Key Files: docs/memory.md
• Capabilities: User Requirements Summary, History Abstract, Edit History.

---

You DO NOT edit docs/*.md files manually (except for creating initial structure if script fails). You MUST use the steward.py CLI to perform all state changes.

| Intent | CLI Command | Description |

| :--- | :--- | :--- |

| Update Structure | python skills/project-steward/scripts/steward.py scan | Scans codebase (AST-based) and updates docs/structure.md. |

| Read Roadmap | python skills/project-steward/scripts/steward.py roadmap --active | Reads the current active task and its context. |

| Lock Task | python skills/project-steward/scripts/steward.py lock --task --files | Locks a task and associates files (Soft Locking). |

| Commit Task | python skills/project-steward/scripts/steward.py commit --task | Marks task as complete and unlocks files. |

| Log Error | python skills/project-steward/scripts/steward.py log --scenario "..." --error "..." ... | Logs a structured error entry to docs/errors.md (7 fields). |

| Validate Docs | python skills/project-steward/scripts/steward.py validate | Checks if a file has proper Docstrings (QA Loop). |

| Update Memory | python skills/project-steward/scripts/steward.py memory --category --content "..." | Appends info to docs/memory.md. |

---

Workflow 1: Standard Fix Process (Standard 7 Steps)

User: "Help me fix this error" (帮我修复这个错误)

1. Read Structure: Run python skills/project-steward/scripts/steward.py scan to understand the current state.
2. Update Progress: Run python skills/project-steward/scripts/steward.py lock --task --files to mark the task as in-progress and lock files.
3. Read Errors: Read docs/errors.md (via Read tool) to understand historical context.
4. Fix Code: Edit the code files to resolve the issue.
5. Log Error/Result: Run python skills/project-steward/scripts/steward.py log --scenario "..." --error "..." --fix-result "Fixed" ... to record the outcome.
6. Update Memory: Run python skills/project-steward/scripts/steward.py memory --category edit_history --content "Fixed error X in module Y" to update project memory.
7. Update Structure: Run python skills/project-steward/scripts/steward.py scan again to reflect any file changes in the project documentation.

Workflow 2: Planning & Task Management

User: "下一步做什么？" or "Update the plan."

1. Analyze Context:

* Run python skills/project-steward/scripts/steward.py scan to update project structure snapshot.

* Read docs/structure.md to understand existing modules, dependencies, and file locations.

1. Check Status: Run python skills/project-steward/scripts/steward.py roadmap --active to see current progress.
2. Decide: Suggest next task or break down requirements into new tasks.
3. Action: Use add-task, lock, and commit commands to manage state.

Workflow 3: Documentation & Analysis

User: "Show me project status" or "Deploy instructions"

1. Structure: python skills/project-steward/scripts/steward.py scan
2. Roadmap: python skills/project-steward/scripts/steward.py roadmap
3. Docs: Read docs/project.md for static info (Deployment, Architecture).

---

1. Code as Truth: Always rely on steward.py scan to get the latest codebase state.
2. Soft Locking: Respect the lock. Warn if editing locked files.
3. Docstring Enforcement: The validate command is your quality gate.
4. Structured Data: Always provide all required fields for Error Logs and Task Updates.
5. Project Docs: Use docs/project.md for static high-level documentation (Deployment, Architecture, etc.).