From 6df69ddf75eff820ddbe366b4ea4e5922411c57a Mon Sep 17 00:00:00 2001 From: dafang Date: Thu, 2 Jul 2026 21:32:23 +0800 Subject: [PATCH] refactor(codestable): simplify skill entrypoints --- .../skill-entry-simplification-checklist.yaml | 43 +++ ...ll-entry-simplification-refactor-design.md | 170 ++++++++++ .gitignore | 1 - README.en.md | 218 ++++--------- README.md | 223 ++++--------- SKILL_CATALOG.en.md | 61 ++-- SKILL_CATALOG.md | 61 ++-- WORKFLOW.en.md | 46 ++- WORKFLOW.md | 42 ++- .../codestable/skills/cs-brainstorm/SKILL.md | 36 +-- .../skills/cs-brainstorm/reference.md | 2 +- .../codestable/skills/cs-code-review/SKILL.md | 138 ++------ .../references/independent-review/protocol.md | 101 ++++++ .../references/report-template.md | 2 +- plugins/codestable/skills/cs-doc-api/SKILL.md | 144 +-------- .../skills/cs-doc-tutorial/SKILL.md | 159 +--------- .../codestable/skills/cs-docs-neat/SKILL.md | 13 +- plugins/codestable/skills/cs-docs/SKILL.md | 81 +++++ .../skills/cs-docs/references/api/protocol.md | 134 ++++++++ .../references/api}/reference.md | 2 +- .../cs-docs/references/tutorial/protocol.md | 149 +++++++++ plugins/codestable/skills/cs-epic/SKILL.md | 85 +++++ .../cs-epic/references/goal/protocol.md | 219 +++++++++++++ .../goal/support/goal-command-template.md | 7 + .../goal/support}/protocol-audit.md | 0 .../goal/support}/protocol-feature-loop.md | 12 +- .../goal/support}/protocol-gates.md | 2 +- .../references/goal/support}/protocol.md | 0 .../cs-epic/references/planning/protocol.md | 268 ++++++++++++++++ .../references/planning}/reference.md | 8 +- .../planning/support}/codebase-design.md | 2 +- .../cs-epic/references/review/protocol.md | 274 ++++++++++++++++ .../codestable/skills/cs-feat-accept/SKILL.md | 290 +---------------- .../skills/cs-feat-design-review/SKILL.md | 291 +---------------- .../codestable/skills/cs-feat-design/SKILL.md | 282 +---------------- plugins/codestable/skills/cs-feat-ff/SKILL.md | 224 +------------ .../codestable/skills/cs-feat-impl/SKILL.md | 297 +----------------- plugins/codestable/skills/cs-feat-qa/SKILL.md | 268 +--------------- plugins/codestable/skills/cs-feat/SKILL.md | 192 +++++------ .../cs-feat/references/acceptance/protocol.md | 280 +++++++++++++++++ .../references/acceptance}/reference.md | 6 +- .../references/design-review/protocol.md | 281 +++++++++++++++++ .../cs-feat/references/design/protocol.md | 272 ++++++++++++++++ .../references/design}/reference.md | 8 +- .../design/support}/codebase-design.md | 2 +- .../design/support}/intent-template.md | 2 +- .../references/fastforward/protocol.md | 214 +++++++++++++ .../references/implementation/protocol.md | 287 +++++++++++++++++ .../implementation/support}/reference.md | 14 +- .../references/implementation/support}/tdd.md | 6 +- .../skills/cs-feat/references/qa/protocol.md | 258 +++++++++++++++ .../skills/cs-issue-analyze/SKILL.md | 176 +---------- .../codestable/skills/cs-issue-fix/SKILL.md | 171 +--------- .../skills/cs-issue-report/SKILL.md | 155 +-------- plugins/codestable/skills/cs-issue/SKILL.md | 124 ++++---- .../cs-issue/references/analyze/protocol.md | 166 ++++++++++ .../cs-issue/references/fix/protocol.md | 161 ++++++++++ .../references/fix}/reference.md | 4 +- .../cs-issue/references/report/protocol.md | 145 +++++++++ plugins/codestable/skills/cs-onboard/SKILL.md | 10 +- .../cs-onboard/reference/system-overview.md | 109 ------- .../approval-conventions.md | 8 +- .../branch-guard-hooks.md | 0 .../code-dimensions.md | 0 .../execution-conventions.md | 0 .../goal-conventions.md | 0 .../maintainer-notes.md | 2 +- .../requirement-example.md | 0 .../shared-conventions.md | 38 +-- .../spec-governance-tools.md | 0 .../cs-onboard/references/system-overview.md | 84 +++++ .../tools-context.md | 0 .../{reference => references}/tools.md | 2 +- .../cs-onboard/tools/codestable_common.py | 2 + .../codestable/skills/cs-refactor-ff/SKILL.md | 136 +------- .../codestable/skills/cs-refactor/SKILL.md | 254 +++------------ .../references/fastforward/protocol.md | 126 ++++++++ .../library}/methods-architecture.md | 0 .../library}/methods-l4.md | 0 .../library}/methods.md | 0 .../library}/refusal-routing.md | 0 .../library}/scan-checklist-format.md | 2 +- .../references/standard/protocol.md | 241 ++++++++++++++ plugins/codestable/skills/cs-req/SKILL.md | 10 +- .../skills/cs-roadmap-impl-goal/SKILL.md | 231 +------------- .../references/goal-command-template.md | 7 - .../skills/cs-roadmap-review/SKILL.md | 284 +---------------- plugins/codestable/skills/cs-roadmap/SKILL.md | 278 +--------------- plugins/codestable/skills/cs/SKILL.md | 228 ++++---------- tests/test_codestable_worktree_gate.py | 6 +- tests/test_plugin_package.py | 43 ++- tests/test_skill_entry_simplification.py | 297 ++++++++++++++++++ tools/check-plugin-package.py | 30 ++ 93 files changed, 5243 insertions(+), 4464 deletions(-) create mode 100644 .codestable/refactors/2026-07-01-skill-entry-simplification/skill-entry-simplification-checklist.yaml create mode 100644 .codestable/refactors/2026-07-01-skill-entry-simplification/skill-entry-simplification-refactor-design.md create mode 100644 plugins/codestable/skills/cs-code-review/references/independent-review/protocol.md create mode 100644 plugins/codestable/skills/cs-docs/SKILL.md create mode 100644 plugins/codestable/skills/cs-docs/references/api/protocol.md rename plugins/codestable/skills/{cs-doc-api => cs-docs/references/api}/reference.md (88%) create mode 100644 plugins/codestable/skills/cs-docs/references/tutorial/protocol.md create mode 100644 plugins/codestable/skills/cs-epic/SKILL.md create mode 100644 plugins/codestable/skills/cs-epic/references/goal/protocol.md create mode 100644 plugins/codestable/skills/cs-epic/references/goal/support/goal-command-template.md rename plugins/codestable/skills/{cs-roadmap-impl-goal/references => cs-epic/references/goal/support}/protocol-audit.md (100%) rename plugins/codestable/skills/{cs-roadmap-impl-goal/references => cs-epic/references/goal/support}/protocol-feature-loop.md (86%) rename plugins/codestable/skills/{cs-roadmap-impl-goal/references => cs-epic/references/goal/support}/protocol-gates.md (97%) rename plugins/codestable/skills/{cs-roadmap-impl-goal/references => cs-epic/references/goal/support}/protocol.md (100%) create mode 100644 plugins/codestable/skills/cs-epic/references/planning/protocol.md rename plugins/codestable/skills/{cs-roadmap => cs-epic/references/planning}/reference.md (97%) rename plugins/codestable/skills/{cs-roadmap/references => cs-epic/references/planning/support}/codebase-design.md (93%) create mode 100644 plugins/codestable/skills/cs-epic/references/review/protocol.md create mode 100644 plugins/codestable/skills/cs-feat/references/acceptance/protocol.md rename plugins/codestable/skills/{cs-feat-accept => cs-feat/references/acceptance}/reference.md (94%) create mode 100644 plugins/codestable/skills/cs-feat/references/design-review/protocol.md create mode 100644 plugins/codestable/skills/cs-feat/references/design/protocol.md rename plugins/codestable/skills/{cs-feat-design => cs-feat/references/design}/reference.md (97%) rename plugins/codestable/skills/{cs-feat-design/references => cs-feat/references/design/support}/codebase-design.md (94%) rename plugins/codestable/skills/{cs-feat-design/references => cs-feat/references/design/support}/intent-template.md (77%) create mode 100644 plugins/codestable/skills/cs-feat/references/fastforward/protocol.md create mode 100644 plugins/codestable/skills/cs-feat/references/implementation/protocol.md rename plugins/codestable/skills/{cs-feat-impl/references => cs-feat/references/implementation/support}/reference.md (92%) rename plugins/codestable/skills/{cs-feat-impl/references => cs-feat/references/implementation/support}/tdd.md (89%) create mode 100644 plugins/codestable/skills/cs-feat/references/qa/protocol.md create mode 100644 plugins/codestable/skills/cs-issue/references/analyze/protocol.md create mode 100644 plugins/codestable/skills/cs-issue/references/fix/protocol.md rename plugins/codestable/skills/{cs-issue-fix => cs-issue/references/fix}/reference.md (91%) create mode 100644 plugins/codestable/skills/cs-issue/references/report/protocol.md delete mode 100644 plugins/codestable/skills/cs-onboard/reference/system-overview.md rename plugins/codestable/skills/cs-onboard/{reference => references}/approval-conventions.md (95%) rename plugins/codestable/skills/cs-onboard/{reference => references}/branch-guard-hooks.md (100%) rename plugins/codestable/skills/cs-onboard/{reference => references}/code-dimensions.md (100%) rename plugins/codestable/skills/cs-onboard/{reference => references}/execution-conventions.md (100%) rename plugins/codestable/skills/cs-onboard/{reference => references}/goal-conventions.md (100%) rename plugins/codestable/skills/cs-onboard/{reference => references}/maintainer-notes.md (95%) rename plugins/codestable/skills/cs-onboard/{reference => references}/requirement-example.md (100%) rename plugins/codestable/skills/cs-onboard/{reference => references}/shared-conventions.md (85%) rename plugins/codestable/skills/cs-onboard/{reference => references}/spec-governance-tools.md (100%) create mode 100644 plugins/codestable/skills/cs-onboard/references/system-overview.md rename plugins/codestable/skills/cs-onboard/{reference => references}/tools-context.md (100%) rename plugins/codestable/skills/cs-onboard/{reference => references}/tools.md (98%) create mode 100644 plugins/codestable/skills/cs-refactor/references/fastforward/protocol.md rename plugins/codestable/skills/cs-refactor/{reference => references/library}/methods-architecture.md (100%) rename plugins/codestable/skills/cs-refactor/{reference => references/library}/methods-l4.md (100%) rename plugins/codestable/skills/cs-refactor/{reference => references/library}/methods.md (100%) rename plugins/codestable/skills/cs-refactor/{reference => references/library}/refusal-routing.md (100%) rename plugins/codestable/skills/cs-refactor/{reference => references/library}/scan-checklist-format.md (99%) create mode 100644 plugins/codestable/skills/cs-refactor/references/standard/protocol.md delete mode 100644 plugins/codestable/skills/cs-roadmap-impl-goal/references/goal-command-template.md create mode 100644 tests/test_skill_entry_simplification.py diff --git a/.codestable/refactors/2026-07-01-skill-entry-simplification/skill-entry-simplification-checklist.yaml b/.codestable/refactors/2026-07-01-skill-entry-simplification/skill-entry-simplification-checklist.yaml new file mode 100644 index 0000000..86f33be --- /dev/null +++ b/.codestable/refactors/2026-07-01-skill-entry-simplification/skill-entry-simplification-checklist.yaml @@ -0,0 +1,43 @@ +refactor: 2026-07-01-skill-entry-simplification +status: done +steps: + - id: document-design + title: Record the 22 design decisions and target architecture + status: done + - id: migrate-feature + title: Move feature stage rules under cs-feat references and thin feature compatibility entries + status: done + - id: migrate-issue + title: Move issue stage rules under cs-issue references and thin issue compatibility entries + status: done + - id: migrate-refactor + title: Move refactor fastforward rules under cs-refactor references and thin cs-refactor-ff + status: done + - id: add-docs + title: Add cs-docs and make tutorial/api skills compatibility entries + status: done + - id: add-epic + title: Add cs-epic and make roadmap skills compatibility entries + status: done + - id: update-docs + title: Update README, WORKFLOW, catalogs, shared conventions, and skill allowlists + status: done + - id: add-tests + title: Add line-limit and compatibility-entry migration tests + status: done + - id: verify + title: Run available validation and test suite + status: done +checks: + - id: markdown-line-limit + title: All Markdown files are at or below 300 lines + status: passed + - id: old-names-preserved + title: Historical stage skill names still exist + status: passed + - id: main-docs-updated + title: User-facing docs recommend main entries and list compatibility entries separately + status: passed + - id: package-validation-updated + title: Plugin validation accepts cs-docs and cs-epic + status: passed diff --git a/.codestable/refactors/2026-07-01-skill-entry-simplification/skill-entry-simplification-refactor-design.md b/.codestable/refactors/2026-07-01-skill-entry-simplification/skill-entry-simplification-refactor-design.md new file mode 100644 index 0000000..8e76b5b --- /dev/null +++ b/.codestable/refactors/2026-07-01-skill-entry-simplification/skill-entry-simplification-refactor-design.md @@ -0,0 +1,170 @@ +--- +doc_type: refactor-design +refactor: 2026-07-01-skill-entry-simplification +status: approved +scope: CodeStable skill entrypoint simplification +summary: Collapse user-facing CodeStable workflows into stable main entries while keeping old stage skills as compatibility entries. +--- + +# Skill Entry Simplification Refactor Design + +## 1. Goal + +Simplify the CodeStable skill system from many user-facing stage skills into a smaller set of main workflow entries. + +Users should normally call one main skill for a workflow: + +- `cs-feat` for feature work +- `cs-issue` for issue fixing +- `cs-refactor` for refactoring +- `cs-docs` for external documentation writing +- `cs-docs-neat` for documentation and memory hygiene +- `cs-epic` for large feature groups +- `cs-code-review` for cross-cutting implementation review +- `cs` only for choosing a main entry + +Old stage skills remain available forever as compatibility entries. They must not preserve independent process logic. + +## 2. Constraints + +- Keep every Markdown file at or below 300 lines. +- When updating skills, also update related skill descriptions and user-facing docs. +- Preserve old skill names so historical users and prompts do not break. +- Do not bulk-migrate historical `.codestable` artifacts. +- Keep `roadmap` as the internal storage/doc_type model for the first `cs-epic` version. +- Do not turn compatibility entries into "please rerun another skill" dead ends; they must continue the current run. + +## 3. Decisions From The Design Interview + +1. Simplify user-visible entrypoints first; do not force a reduction in physical file count. +2. Keep old stage skills long term, but demote them to compatibility entries. +3. Keep `cs-code-review` as a public cross-cutting gate. +4. Demote `cs-feat-ff` to a compatibility entry for `cs-feat` fastforward mode. +5. Make `cs-issue` the only recommended issue entry; demote `cs-issue-*`. +6. Add `cs-docs` for external documentation writing. +7. Keep `cs-docs-neat` independent; it is a hygiene/sync workflow, not normal doc writing. +8. Add `cs-epic` as the recommended large-demand entry. +9. Keep `cs` as a light router to main entries only. +10. Make `cs-refactor` the only recommended refactor entry; demote `cs-refactor-ff`. +11. Use a uniform compatibility entry template. +12. Compatibility entries load the main protocol file; they do not invoke a second skill command. +13. Compatibility entry `description` should state the workflow/stage intent, not low-level path details. +14. Main entries define `requested_stage` and `requested_mode` semantics. +15. Perform a soft migration: keep old skill names, but move thick rules out of old stage skills. +16. Update user-facing docs and shared conventions; do not rewrite historical artifacts. +17. Main entries are continuous orchestrators with human checkpoints, not unchecked automation. +18. Main entries resume from repository facts first; stage/mode hints are secondary. +19. Add lightweight tests for Markdown line limits, compatibility entries, and skill lists. +20. First implementation includes full rule migration, not just skeletons. +21. `cs-epic` prepares the `/goal` command but does not execute it. +22. User-facing docs use `epic`; internal paths and doc_type may still say `roadmap`. + +## 4. Target Shape + +### Feature + +- Main entry: `cs-feat` +- Compatibility entries: `cs-feat-design`, `cs-feat-design-review`, `cs-feat-impl`, `cs-feat-qa`, `cs-feat-accept`, `cs-feat-ff` +- Internal references under `cs-feat/references/` +- `cs-feat` orchestrates design, design review, user approval, implementation, code review, QA, and acceptance. +- `cs-code-review` remains the implementation review authority. + +### Issue + +- Main entry: `cs-issue` +- Compatibility entries: `cs-issue-report`, `cs-issue-analyze`, `cs-issue-fix` +- Internal references under `cs-issue/references/` +- `cs-issue` handles report, analysis, fix, validation, fix note, and code-review handoff. + +### Refactor + +- Main entry: `cs-refactor` +- Compatibility entry: `cs-refactor-ff` +- Internal references under `cs-refactor/references/` +- `cs-refactor` chooses standard or fastforward mode. +- Fastforward mode is allowed only when behavior is unchanged, scope is small, and tests can self-prove safety. + +### Docs + +- Main entry: `cs-docs` +- Compatibility entries: `cs-doc-tutorial`, `cs-doc-api` +- Internal references under `cs-docs/references/` +- `cs-docs` covers external tutorial/user-guide and API reference writing only. +- `cs-docs-neat` stays public and independent. + +### Epic + +- Main entry: `cs-epic` +- Compatibility entries: `cs-roadmap`, `cs-roadmap-review`, `cs-roadmap-impl-goal` +- Internal references under `cs-epic/references/` +- `cs-epic` plans the epic, reviews it, designs child features, prepares the goal execution package, and prints the `/goal` command. +- Storage remains `.codestable/roadmap/{slug}/` for now. + +## 5. Compatibility Entry Contract + +Each compatibility `SKILL.md` should be short and follow the same pattern: + +```markdown +--- +name: {old-skill} +description: {Workflow} compatibility entry. Old calls are preserved; execution enters {main-skill} {stage/mode}. +--- + +# {old-skill} + +This skill is a long-term compatibility entry for `{main-skill}`. +It does not maintain independent workflow rules. + +Entry intent: `{requested_stage: ...}` or `{requested_mode: ...}` + +Execution rules: +1. Load the registered `{main-skill}` skill by skill name as the authoritative main protocol; do not use sibling-directory relative paths as the primary mechanism. +2. Continue this run under that main protocol with the entry intent above. +3. Do not ask the user to rerun `{main-skill}`. +4. If the runtime cannot load the main protocol, stop and report that the compatibility entry cannot continue. +``` + +Exact wording can vary slightly for `cs-roadmap*` because `cs-epic` is a different name from the historical storage model. + +## 6. Main Entry Contract + +Each main entry `SKILL.md` should contain: + +- Purpose and user-facing workflow boundary +- Supported `requested_stage` values +- Supported `requested_mode` values +- Repository-facts-first resume rules +- Human checkpoints +- Reference loading map +- Completion criteria +- Compatibility entry list + +Thick stage details should live in reference files, not in the main `SKILL.md`. + +## 7. Implementation Steps + +1. Create or revise main entry reference files for feature, issue, refactor, docs, and epic. +2. Rewrite old stage skill files into compatibility entries. +3. Add `cs-docs` and `cs-epic` skill directories. +4. Update `README.md`, `WORKFLOW.md`, `SKILL_CATALOG.md`, and English mirrors when present. +5. Update `plugins/codestable/skills/cs-onboard/references/shared-conventions.md`. +6. Update skill-name allowlists and package checks. +7. Add tests for line limits, compatibility entry shape, and new main entries. +8. Run targeted tests, then the full available test suite. + +## 8. Risks + +- Rules can be lost during migration if a stage skill is thinned before its content is copied into references. +- Cross-references can drift if README, catalog, workflow, and shared conventions are not updated together. +- `cs-epic` naming can confuse users if docs imply `epic` and `roadmap` are separate concepts. +- Compatibility entries can become unusable if they tell users to manually call the main entry instead of continuing the current run. + +## 9. Acceptance Criteria + +- Main documentation recommends main entries, not stage skills. +- Compatibility entries remain discoverable but are clearly labeled as compatibility entries. +- No Markdown file exceeds 300 lines. +- New main entries `cs-docs` and `cs-epic` are included in package validation. +- Old stage skill names remain present. +- Thick workflow rules exist under main entry references. +- Tests cover the migration invariants above. diff --git a/.gitignore b/.gitignore index ab2077b..ba307cb 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,3 @@ __pycache__ *.pyc .DS_Store -.codestable/ diff --git a/README.en.md b/README.en.md index d5cc097..02dc37a 100644 --- a/README.en.md +++ b/README.en.md @@ -12,7 +12,7 @@ Tired of OpenSpec's flimsiness, Oh-My-OpenAgent's over-engineering, and Superpow

Status - CodeStable Skills + CodeStable Skills License

@@ -149,24 +149,26 @@ CodeStable models real coding work as a set of **entities** and **flows**. | Entity | Slug | What it does | |------|------|--------| -| **Requirement** | requirements | User stories + domain glossary (CONTEXT.md) + architecture decisions (ADRs). The escape hatch — when code rots, you can throw it all out and let AI regenerate from these | -| **Roadmap** | roadmap | "I want a permission system" — too big to throw at AI as a feature; cut it into a roadmap and advance step by step | -| **Goal** | goals | Bounded start/end: write a start report, then let AI iterate autonomously on implementation/validation, with subagent functional acceptance before completion | -| **Feature** | feature | The actual engineering execution. Human and AI collaborate, jointly responsible for design / implementation / acceptance | -| **Issue** | issue | The bug list after release. AI and human solve it together | -| **Refactor** | refactor | Cleanup process when code rots (beta) | -| **Compound** | compound | The compounding-engineering knowledge base — pitfalls, tricks, investigation notes | +| **Requirement** | requirements | User stories + domain glossary (CONTEXT.md) + architecture decisions (ADRs). The escape hatch when code rots | +| **Epic** | epic | Large demand entry such as "I want a permission system"; user-facing docs call it epic while v1 still stores internal artifacts under `.codestable/roadmap/` | +| **Goal** | goals | Bounded start/end: write a start report, then let AI iterate autonomously with subagent functional acceptance before completion | +| **Feature** | feature | Engineering execution where human and AI share responsibility for design, implementation, QA, and acceptance | +| **Issue** | issue | Bug records and fixes after something should already work | +| **Refactor** | refactor | Behavior-preserving cleanup when code rots (beta) | +| **Compound** | compound | The compounding-engineering knowledge base: pitfalls, tricks, decisions, and investigation notes | ### Flows -| Flow | Key skill chain | Notes | +| Flow | Recommended main entry | Notes | |------|------------|------| -| **Feature delivery** | `cs-feat` → `cs-feat-design` → `cs-feat-design-review` → `cs-feat-impl` → `cs-code-review` → `cs-feat-qa` → `cs-feat-accept` | Think it through → design review → step-by-step coding → code review → QA → acceptance | -| **Goal achievement** | `cs-goal` | Bounded start/end → interview/grill + start report → autonomous implement/validate/iterate → subagent functional acceptance before completion | -| **Issue fixing** | `cs-issue-report` → `cs-issue-analyze` → `cs-issue-fix` → `cs-code-review` | Tell AI what's wrong → AI finds the root cause → AI fixes precisely → independent review before commit | -| **Refactoring** | `cs-refactor` (beta) → `cs-code-review` | Architectural rot doesn't happen overnight. AI assists, but **humans refactor**. Still iterating — feedback welcome | +| **Feature delivery** | `cs-feat` | End-to-end design → design review → implementation → `cs-code-review` → QA → acceptance | +| **Epic delivery** | `cs-epic` | Plan a large demand, review it, design child features, prepare a goal package, then print `/goal` | +| **Goal achievement** | `cs-goal` | Bounded start/end → interview/grill + start report → autonomous implement/validate/iterate → subagent functional acceptance | +| **Issue fixing** | `cs-issue` | End-to-end report → analyze → fix → `cs-code-review` | +| **Refactoring** | `cs-refactor` | Behavior-preserving cleanup; standard or fastforward mode, followed by `cs-code-review` | +| **External docs** | `cs-docs` | Developer guides, user guides, and API references; hygiene stays in `cs-docs-neat` | -`cs-code-review` is the cross-cutting quality gate at the tail of every execution flow, before commit — feature, fast path, issue fixing, and refactoring all route their pre-commit diff review through it. At a phase or milestone boundary, use `cs-docs-neat` to reconcile `.codestable/`, README/docs, `CLAUDE.md` / `AGENTS.md`, and agent memory so docs do not drift from code. +`cs-code-review` is the cross-cutting quality gate at the tail of execution flows, before commit. At a phase or milestone boundary, use `cs-docs-neat` to reconcile `.codestable/`, README/docs, `CLAUDE.md` / `AGENTS.md`, and agent memory so docs do not drift from code. > Strong branch protection: `cs-onboard` can optionally release the `codestable-ai-branch-guard` hook, which blocks AI from implementing directly on `main`/`master` and forces a worktree. See the "branch protection hook" section in `cs-onboard`. @@ -174,152 +176,66 @@ CodeStable models real coding work as a set of **entities** and **flows**. ## Skill catalog - - - - - - - - - - - - - - - - - - - - - - - - -
GroupSkillPurpose
Root entrycsUnified entry — introduces the system and routes open-ended intents to the right cs-* skill. Call it when you don't know which one fits
Onboardcs-onboardBring CodeStable into a new repo or one with scattered docs
Requirement & domaincs-reqCurate / accumulate capability vision docs
cs-domainMaintain requirements/CONTEXT.md glossary + requirements/adrs/ architecture decisions (3-criteria gate + Nygard 4 sections) + single/multi context topology
Roadmapcs-roadmapUp-front planning for a big chunk of work: high-level design + interface contracts + sub-feature breakdown
Discussion entrycs-brainstormTriage when ideas are still fuzzy: route to design / continue in a feature / hand off to roadmap
Goalcs-goalBounded start/end: write a start report, let AI iterate autonomously, with subagent functional acceptance before completion
Feature flowcs-featSub-flow entry for new features
cs-feat-designDraft {slug}-design.md as the single input for what follows
cs-feat-implCode in the order the design lays out
cs-code-reviewCross-cutting read-only code review gate before commit; produces {slug}-review.md
cs-feat-acceptVerify implementation against the design layer by layer; close the loop
cs-feat-ffUltra-light lane: no design, no phases, AI just does it
Issue flowcs-issueSub-flow entry for issue fixing
cs-issue-reportTurn the problem in your head into a reproducible, traceable report
cs-issue-analyzeFind root cause, assess fix risk, propose options
cs-issue-fixTargeted fix + verification + write fix-note
Refactor flowcs-refactor(beta) Main refactor flow
cs-refactor-ff(beta) Light refactor lane
Knowledge sinkcs-keepSink pitfalls / tricks / decisions / exploration into compound/ as plain markdown, searched via grep
Outward docscs-doc-tutorialOutward-facing dev / user guides (task-oriented: how to use X to do Y)
cs-doc-apiAPI reference reverse-engineered from source (entry-by-entry, parts lookup)
+### Recommended main entries -See [SKILL_CATALOG.en.md](./SKILL_CATALOG.en.md) for the full catalog. In daily use, call `/cs` when you are unsure; it routes your intent to the right skill. +| Group | Skill | Purpose | +|---|---|---| +| Root | `cs` | Lightweight triage to the right main entry | +| Onboard | `cs-onboard` | Install CodeStable into a repository | +| Requirements & domain | `cs-req` / `cs-domain` | Capture capability intent, domain terms, ADRs, and context topology | +| Epic | `cs-epic` | Large demand planning, review, child feature design, and goal package | +| Brainstorm | `cs-brainstorm` | Triage fuzzy ideas into feature, epic, or brainstorm notes | +| Goal | `cs-goal` | Autonomous iteration from a bounded start state to acceptance | +| Feature | `cs-feat` | End-to-end feature workflow | +| Issue | `cs-issue` | End-to-end issue workflow | +| Refactor | `cs-refactor` | Behavior-preserving refactor workflow | +| Review | `cs-code-review` | Cross-cutting read-only implementation review gate | +| Audit | `cs-audit` | Scan for bugs, security, performance, maintainability, and architecture drift | +| Knowledge | `cs-keep` / `cs-note` | Capture durable knowledge or short startup-critical notes | +| External docs | `cs-docs` | Developer guides, user guides, and API references | +| Docs hygiene | `cs-docs-neat` | Sync `.codestable/`, README/docs, agent entries, and memory | + +### Long-term compatibility entries + +Old skill names remain usable but only enter the corresponding main workflow: + +- Feature: `cs-feat-design` / `cs-feat-design-review` / `cs-feat-impl` / `cs-feat-qa` / `cs-feat-accept` / `cs-feat-ff` +- Issue: `cs-issue-report` / `cs-issue-analyze` / `cs-issue-fix` +- Refactor: `cs-refactor-ff` +- Docs: `cs-doc-tutorial` / `cs-doc-api` +- Epic: `cs-roadmap` / `cs-roadmap-review` / `cs-roadmap-impl-goal` + +See [SKILL_CATALOG.en.md](./SKILL_CATALOG.en.md) for the full catalog. In daily use, call `/cs` when you are unsure. --- ## Workflow at a glance -CodeStable's skills are **layered + event-driven**: root routing, onboard, long-lived archives, roadmap planning, feature / issue / refactor execution flows, and cross-cut knowledge sinking. +CodeStable is layered and event-driven: ```text -═══════════════════════════════════════════════════════════════════════ - Root entry · routing (callable any time) -─────────────────────────────────────────────────────────────────────── - cs ──▶ Introduce the system / route open-ended intent to a sub-skill - (does nothing itself — only triages and points) -═══════════════════════════════════════════════════════════════════════ - │ - ┌───────────────┼───────────────┐ - ▼ ▼ ▼ - (not onboarded) (onboarded) (just want to learn) - go to phase 0 jump to L1~4 / cross-cut quick read - │ - ▼ -═══════════════════════════════════════════════════════════════════════ - Phase 0 · Onboard (runs once per project) -─────────────────────────────────────────────────────────────────────── - cs-onboard ──▶ Generate .codestable/ skeleton + release reference/, tools/ - optionally release codestable-ai-branch-guard hook -═══════════════════════════════════════════════════════════════════════ - │ - ▼ -═══════════════════════════════════════════════════════════════════════ - Layer 1 · Long-lived archive ("what the system looks like now") -─────────────────────────────────────────────────────────────────────── - cs-req ──▶ .codestable/requirements/{slug}.md capability vision - cs-domain ──▶ .codestable/requirements/CONTEXT.md domain glossary - .codestable/requirements/adrs/NNN-*.md ADRs (3-criteria gate) - CONTEXT-MAP.md present → nest per bounded context -═══════════════════════════════════════════════════════════════════════ - │ - ▼ -═══════════════════════════════════════════════════════════════════════ - Layer 2 · Planning ("how we plan to deliver this big thing next") -─────────────────────────────────────────────────────────────────────── - cs-roadmap ──▶ .codestable/roadmap/{slug}/ - Turn "I want X" into a complete up-front plan: - ① High-level design — module / component split - ② Architectural detail — interface contracts - ③ Sub-features — broken into executable units - ② is a hard input for feature-design - (Small needs skip this layer and go straight to L3) - - cs-roadmap-review ✦Gate ──▶ independent planning review - → {slug}-roadmap-review.md - - cs-roadmap-impl-goal ──▶ prepare design/checklist/design-review - for each sub-feature - → emit ready-to-run /goal prompts -═══════════════════════════════════════════════════════════════════════ - │ - ▼ -═══════════════════════════════════════════════════════════════════════ - Discussion entry (optional · enter when fuzzy, route after triage) -─────────────────────────────────────────────────────────────────────── - ┌── case 1 clear enough ──▶ cs-feat-design - cs-brainstorm ────────▶┼── case 2 small + decided ─▶ feature flow - └── case 3 big with one word ─▶ cs-roadmap -═══════════════════════════════════════════════════════════════════════ - │ - ▼ -═══════════════════════════════════════════════════════════════════════ - Layer 3 · Execution flows (pick one per event type) -─────────────────────────────────────────────────────────────────────── - - ▸ Event: new capability ┌──────────┐ - cs-feat-design ─▶ cs-feat-design-review ✦Gate ─▶ │ features │ - cs-feat-impl ─▶ cs-code-review ✦Gate ─▶ │ /YYYY-…/ │ - cs-feat-qa ✦Gate ─▶ cs-feat-accept └──────────┘ - - cs-feat-ff ──(light lane, skips design/accept)─▶ - - ▸ Event: fix a defect ┌──────────┐ - cs-issue-report ─▶ cs-issue-analyze ─▶ cs-issue-fix ─▶ │ issues │ - cs-code-review │ /YYYY-…/ │ - └──────────┘ - - ▸ Event: code rot (beta) ┌──────────┐ - cs-refactor / cs-refactor-ff ─▶ cs-code-review │refactors │ - │ /YYYY-…/ │ - └──────────┘ - - ▸ Event: bounded goal ┌──────────┐ - cs-goal ──▶ start report ─▶ autonomous impl/verify loop │ goals │ - ─▶ subagent functional acceptance │ /{slug}/ │ - └──────────┘ -═══════════════════════════════════════════════════════════════════════ - │ - ┌───────────────────┴───────────────────┐ - ▼ trigger any time something is reusable ▼ milestone close -═══════════════════════════════════════════════════════════════════════ - Cross-cut · Knowledge sink & docs cleanup -─────────────────────────────────────────────────────────────────────── - cs-keep ──▶ .codestable/compound/YYYY-MM-DD-{slug}.md - plain markdown, no frontmatter, grep to search - next cs-feat-design / cs-issue-analyze greps it - - cs-note ──▶ .codestable/attention.md - - cs-docs-neat ──▶ reconcile .codestable/, README/docs, - CLAUDE.md / AGENTS.md, and agent memory -═══════════════════════════════════════════════════════════════════════ +cs +└── cs-onboard + ├── cs-req / cs-domain + ├── cs-epic # user-facing epic; internally still roadmap storage + ├── cs-goal + ├── cs-brainstorm + ├── cs-feat -> cs-code-review + ├── cs-issue -> cs-code-review + ├── cs-refactor -> cs-code-review + ├── cs-docs + └── cs-keep / cs-note / cs-docs-neat ``` -**How to read this diagram:** +How to read it: -- **Vertical = layers**, not strict time order; long-lived archives are refreshed repeatedly, while the roadmap layer is entered for large needs. -- **✦Gate = explicit blocking points**: design-review, code-review, and QA each produce a report; blocking findings route work back to the matching stage. -- **Layer 3 is event-driven**: new capability goes to feature flow, bugs go to issue flow, rot goes to refactor flow, and bounded outcomes go to goal flow. -- **Cross-cut is the flywheel**: any flow can sink reusable experience through `cs-keep`; `cs-docs-neat` reconciles docs at milestone boundaries. +- `cs` only triages to main entries; it no longer routes users to stage skills. +- `cs-feat`, `cs-issue`, and `cs-refactor` resume from repository facts and stop at human checkpoints. +- `cs-epic` prepares planning and goal packages; v1 still writes `.codestable/roadmap/`. +- `cs-code-review` is the cross-cutting gate; `cs-docs-neat` handles hygiene; `cs-docs` writes outward docs. +- Old stage skills are long-term compatibility entries for historical users. -See [WORKFLOW.en.md](./WORKFLOW.en.md) for another compact workflow summary. +See [WORKFLOW.en.md](./WORKFLOW.en.md) for the compact diagram. --- @@ -402,15 +318,15 @@ your-project/ - `requirements/` is the **long-lived archive** (capability vision + domain glossary CONTEXT.md + decisions adrs/); `roadmap/` is the **planning layer** (what's next), deliberately separated. - `features/` `issues/` `refactors/` use `YYYY-MM-DD-{slug}/` to bundle all related specs in one directory, no crossing. - `compound/` is the **single** knowledge sink directory: plain markdown, no frontmatter, searched via `grep -r`. -- `reference/` is copied in by `cs-onboard`; to change shared conventions, edit the templates under `plugins/codestable/skills/cs-onboard/reference/` so new projects pick them up at onboard time. +- `.codestable/reference/` is copied in by `cs-onboard` from `plugins/codestable/skills/cs-onboard/references/`; to change shared conventions, edit those skill-package templates so new projects pick them up at onboard time. ### Hard constraint -> A skill is an independent install unit. At runtime, **each skill can only see files inside its own package**. References like `B-skill/reference/xxx.md` written in skill A's SKILL.md are **simply unreachable** at runtime. +> A skill is an independent install unit. At runtime, **each skill can only see files inside its own package**. References like `B-skill/references/xxx.md` written in skill A's SKILL.md are **simply unreachable** at runtime. > > Cross-skill shared references must go through the "working project" layer: `cs-onboard` copies them from the skill package to the project's `.codestable/reference/`, and other skills read them via the project-relative path. -To change shared conventions, edit the templates under `plugins/codestable/skills/cs-onboard/reference/`; new projects pick them up at onboard time. See [WORKFLOW.en.md](./WORKFLOW.en.md) for the full directory model and cross-skill reference constraints. +To change shared conventions, edit the templates under `plugins/codestable/skills/cs-onboard/references/`; new projects pick them up at onboard time. See [WORKFLOW.en.md](./WORKFLOW.en.md) for the full directory model and cross-skill reference constraints. --- diff --git a/README.md b/README.md index bb2d83e..9d35974 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@

Status - CodeStable Skills + CodeStable Skills License

@@ -151,22 +151,23 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成 | 实体 | 英文 | 干什么 | |------|------|--------| | **需求** | requirements | 原始用户故事 + 领域术语（CONTEXT.md）+ 架构决策（ADR）。最终的逃生通道——代码烂成一坨屎时，可以摒弃所有代码、让 AI 重新生成 | -| **路线图** | roadmap | "我想要一个权限校验系统"——直接塞 feature AI 接不住，先拆成路线图分步推进；`cs-roadmap-review` 做独立规划审查，`cs-roadmap-impl-goal` 把大需求一路推到 `/goal` 指令 | +| **Epic** | epic | “我想要一个权限校验系统”这类大需求的主入口；用户侧叫 epic，第一版内部仍复用 `.codestable/roadmap/` 和 roadmap doc_type | | **目标** | goals | 限定起点和终点，写起点报告后让 AI 自主迭代实现/验证，完成前用 subagent 做功能验收 | -| **特性** | feature | 实际落地的工程执行过程，人与 AI 共同协作，对 design / 实现 / 验收负责；每个阶段之间有显式的 Gate 卡口（design-review / code-review / qa） | +| **特性** | feature | 实际落地的工程执行过程，人与 AI 共同协作，对 design / 实现 / 验收负责；每个阶段之间有显式的 Gate 卡口 | | **问题** | issue | 开发完成后的 BUG 单子，AI 和人一同解决 | | **重构** | refactor | 代码腐化时的整理过程（beta） | | **知识** | compound | 复利工程的知识库，沉淀踩过的坑、好做法、调研结论（`cs-keep`）；碎片化项目约定写入 `attention.md`（`cs-note`） | ### 流程 -| 流程 | 关键技能链 | 说明 | +| 流程 | 推荐主入口 | 说明 | |------|------------|------| -| **特性引入** | `cs-feat` → `cs-feat-design` → `cs-feat-design-review` *(Gate)* → `cs-feat-impl` → `cs-code-review` *(Gate)* → `cs-feat-qa` *(Gate)* → `cs-feat-accept` | 想清楚 → 方案独立审查 → 逐步编码 → 代码审查 → QA → 验收闭环 | -| **大需求端到端** | `cs-roadmap` → `cs-roadmap-review` *(Gate)* → 用户确认 → `cs-roadmap-impl-goal` → `/goal` 指令 | 大需求拆成路线图 → 独立规划审查 → 逐个 feature 自动推进至验收 | +| **特性引入** | `cs-feat` | 一个入口端到端推进 design → design-review → implementation → `cs-code-review` → QA → acceptance | +| **大需求端到端** | `cs-epic` | 大需求规划 → 规划审查 → 用户确认 → 子 feature design/review → goal 执行包 → 输出 `/goal` 指令 | | **目标达成** | `cs-goal` | 限定起点/终点 → grill 写起点报告 → 自主实现/验证/迭代 → subagent 功能验收 | -| **问题修改** | `cs-issue-report` → `cs-issue-analyze` → `cs-issue-fix` → `cs-code-review` *(Gate)* | 跟 AI 说哪里有问题 → 分析根因 → 定点修复 → 合并前独立评审 | -| **代码重构** | `cs-refactor` (beta) → `cs-code-review` *(Gate)* | 软件架构腐化不是一蹴而就的。AI 辅助重构，但**终归是人在重构**——还在迭代中，欢迎赐教 | +| **问题修改** | `cs-issue` | 一个入口端到端推进 report → analyze → fix → `cs-code-review` | +| **代码重构** | `cs-refactor` | 行为等价重构；内部判定标准模式或 fastforward mode，完成后进入 `cs-code-review` | +| **对外文档** | `cs-docs` | 写或更新开发者指南、用户指南、API 参考；知识库卫生仍由 `cs-docs-neat` 负责 | `cs-code-review` 是各执行流末端、commit 前的横切质量门禁。阶段或里程碑收尾时，用 `cs-docs-neat` 整理 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆，避免文档与代码脱节。 @@ -177,164 +178,64 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成 ## 技能总览 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
分组技能用途
根入口cs统一入口——介绍体系全貌 + 把开放式诉求路由到正确的 cs-* 子技能。不知道用哪个时就喊它
接入cs-onboard把 CodeStable 接入到一个新仓库 / 已有零散文档的仓库；释放 reference/、tools/ 和可选的分支保护 hook
需求 & 领域cs-req整理 / 沉淀能力愿景 doc
cs-domain维护 requirements/CONTEXT.md 术语表 + requirements/adrs/ 架构决策（守门 3 判据 + Nygard 四节）+ 单/多 context 拓扑
路线图cs-roadmap承载一块大需求的事前规划：概设（模块拆分）+ 架构层详设（接口契约 / 共享协议）+ 子 feature 拆解清单
cs-roadmap-reviewroadmap 人审前的独立规划审查 Gate，支持 Paseo 多 agent 辅助审查，产出 {slug}-roadmap-review.md
cs-roadmap-impl-goal大需求端到端编排：roadmap → review → 用户确认 → 逐 feature design/checklist/design-review → 输出可粘贴的 /goal 指令
讨论入口cs-brainstorm想法模糊时的统一讨论入口，做分诊：直接 design / 进 feature 写 brainstorm.md / 移交 roadmap
目标cs-goal限定起点/终点，写起点报告后让 AI 自主迭代实现/验证，完成前用 subagent 做功能验收
特性流程cs-feat新特性子流程入口，按已有产物自动路由到对应阶段
cs-feat-design起草 {slug}-design.md + {slug}-checklist.yaml 作为后续唯一输入
cs-feat-design-review ✦Gatedesign 人审前的独立方案审查，支持 Paseo 多 agent，产出 {slug}-design-review.md
cs-feat-impl按 checklist 推进写代码；也处理 review-fix 和 qa-fix 回流
cs-code-review ✦Gate任何流程实现后、commit 前的横切只读代码审查，产出 {slug}-review.md；blocking 时回到 impl
cs-feat-qa ✦Gate代码审查通过后的本地 QA 验证，产出 {slug}-qa.md；失败时回到 impl 的 qa-fix
cs-feat-accept对照 design 核实现 + review/QA 报告做验收闭环，回写 requirement / roadmap
cs-feat-ff超轻量通道：不写 design、不分阶段，让 AI 直接做
问题流程cs-issue问题修复子流程入口
cs-issue-report把脑子里的问题落成可复现、可追溯的 report
cs-issue-analyze找根因、评估修复风险、给方案
cs-issue-fix定点修复 + 验证 + 写 fix-note
重构流程cs-refactor(beta) 重构主流程：scan → design → apply，每步人工放行
cs-refactor-ff(beta) 轻量重构通道：识别 1-3 条低风险优化，一次确认，原地改
审计cs-audit主动扫描代码：bug 隐患 / 安全漏洞 / 性能问题 / 架构偏离，产出批量发现清单
知识沉淀cs-keep坑点 / 技巧 / 决策 / 调研沉淀到 compound/，纯 markdown，grep 检索
cs-note碎片化项目约定（编译 flag / 路径陷阱 / 命令别名）追加到 attention.md
文档整理cs-docs-neat阶段/里程碑收尾时同步 .codestable/、README/docs、CLAUDE.md / AGENTS.md 和 agent 记忆，防止文档与代码脱节
对外文档cs-doc-tutorial对外的开发者指南 / 用户指南（任务导向，怎么用 X 做 Y）
cs-doc-api从源码反推的 API 参考（逐条目，给读者查零件）
+### 推荐主入口 -完整技能目录见 [SKILL_CATALOG.md](./SKILL_CATALOG.md)。日常不知道用哪个时直接调用 `/cs`，它会按诉求路由到对应技能。 +| 分组 | 技能 | 用途 | +|---|---|---| +| 根入口 | `cs` | 不知道用哪个时轻量分诊到主入口 | +| 接入 | `cs-onboard` | 把 CodeStable 接入新仓库或已有零散文档仓库 | +| 需求 & 领域 | `cs-req` / `cs-domain` | 沉淀能力愿景、领域术语、ADR 和 context 拓扑 | +| Epic | `cs-epic` | 大需求端到端：规划、review、子 feature design、goal 包 | +| 讨论入口 | `cs-brainstorm` | 想法模糊时分诊到 feature、epic 或 brainstorm note | +| 目标 | `cs-goal` | 限定起点/终点后自主迭代到验收 | +| 特性流程 | `cs-feat` | 新特性端到端：design、review、impl、code review、QA、accept | +| 问题流程 | `cs-issue` | 问题修复端到端：report、analyze、fix、review | +| 重构流程 | `cs-refactor` | 行为等价重构，含标准模式和 fastforward mode | +| 横切审查 | `cs-code-review` | 实现完成后、commit 前的只读代码审查 gate | +| 审计 | `cs-audit` | 主动扫描 bug、安全、性能、可维护性和架构偏离 | +| 知识沉淀 | `cs-keep` / `cs-note` | 沉淀 compound 知识或短项目注意事项 | +| 对外文档 | `cs-docs` | 写开发者指南、用户指南、API 参考 | +| 文档收尾 | `cs-docs-neat` | 同步 `.codestable/`、README/docs、agent 入口和记忆 | + +### 长期兼容入口 + +旧技能名继续可用，但只转入对应主入口，不维护独立规则： + +- Feature：`cs-feat-design` / `cs-feat-design-review` / `cs-feat-impl` / `cs-feat-qa` / `cs-feat-accept` / `cs-feat-ff` +- Issue：`cs-issue-report` / `cs-issue-analyze` / `cs-issue-fix` +- Refactor：`cs-refactor-ff` +- Docs：`cs-doc-tutorial` / `cs-doc-api` +- Epic：`cs-roadmap` / `cs-roadmap-review` / `cs-roadmap-impl-goal` + +完整技能目录见 [SKILL_CATALOG.md](./SKILL_CATALOG.md)。日常不知道用哪个时直接调用 `/cs`。 --- ## 工作流示意 -CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动**的：根入口路由、onboard、长效档案、roadmap 规划、feature / issue / refactor 执行流，以及横切的知识沉淀。 +CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动**的： ```text -═══════════════════════════════════════════════════════════════════════ - 根入口 · 路由 （任何时刻都可以调用） -─────────────────────────────────────────────────────────────────────── - cs ──▶ 介绍体系 / 把开放式诉求路由到下面任一具体子技能 - （本身不做事，只做分诊和提示） -═══════════════════════════════════════════════════════════════════════ - │ - ┌───────────────┼───────────────┐ - ▼ ▼ ▼ - （未接入） （已接入） （想了解体系） - 走阶段 0 直达 1~4 层 / 横切 给速读 - │ - ▼ -═══════════════════════════════════════════════════════════════════════ - 阶段 0 · 接入 （只在新项目跑一次） -─────────────────────────────────────────────────────────────────────── - cs-onboard ──▶ 生成 .codestable/ 骨架 + 释放 reference/、tools/ - 可选：释放 codestable-ai-branch-guard hook（强制走 worktree） -═══════════════════════════════════════════════════════════════════════ - │ - ▼ -═══════════════════════════════════════════════════════════════════════ - 第 1 层 · 长效档案（"系统现在长什么样"，只记现状） -─────────────────────────────────────────────────────────────────────── - cs-req ──▶ .codestable/requirements/{slug}.md 能力愿景 - cs-domain ──▶ .codestable/requirements/CONTEXT.md 领域术语 - .codestable/requirements/adrs/NNN-*.md 架构决策（守门 3 判据） -═══════════════════════════════════════════════════════════════════════ - │ - ▼ -═══════════════════════════════════════════════════════════════════════ - 第 2 层 · 规划（"接下来打算怎么做这块大需求"，大需求才需要） -─────────────────────────────────────────────────────────────────────── - cs-roadmap ──▶ .codestable/roadmap/{slug}/ - ① 概设 —— 拆成哪几个模块 / 组件 - ② 架构层详设 —— 接口契约 / 共享协议 - ③ 子 feature —— 多条可执行的 feature 清单 - - cs-roadmap-review ✦Gate ──▶ 独立规划审查 → {slug}-roadmap-review.md - 支持 Paseo 多 agent；不通过不能推进实现 - - cs-roadmap-impl-goal ──▶ 为每个子 feature 完成 design/checklist/design-review - → 输出可直接粘贴的 /goal 指令 -═══════════════════════════════════════════════════════════════════════ - │ - ▼ -═══════════════════════════════════════════════════════════════════════ - 讨论入口（可选 · 想法模糊时进入，做分诊后路由到下游） -─────────────────────────────────────────────────────────────────────── - ┌── case 1 已经够清楚 ──▶ cs-feat-design - cs-brainstorm ────────▶┼── case 2 小需求方向定 ─▶ feature 流（落 brainstorm.md） - └── case 3 大需求只有一个词 ─▶ cs-roadmap -═══════════════════════════════════════════════════════════════════════ - │ - ▼ -═══════════════════════════════════════════════════════════════════════ - 第 3 层 · 执行流程（按事件类型选一条进入） -─────────────────────────────────────────────────────────────────────── - - ▸ 事件：新增能力 ┌──────────────┐ - │ features/ │ - cs-feat-design │ YYYY-MM-DD- │ - │ │ {slug}/ │ - ▼ │ │ - cs-feat-design-review ✦Gate ── 不通过回 design │ -design.md │ - │ 通过 │ -checklist. │ - ▼ │ yaml │ - cs-feat-impl │ -review.md │ - │ │ -qa.md │ - ▼ │ -acceptance │ - cs-code-review ✦Gate ────── blocking 回 impl │ .md │ - │ 通过 └──────────────┘ - ▼ - cs-feat-qa ✦Gate ────────── 失败回 impl - │ 通过 - ▼ - cs-feat-accept - - cs-feat-ff ──(轻量直通车，跳过 design/gate，直接 impl → review)──▶ - - ▸ 事件：修复缺陷 ┌──────────────┐ - cs-issue-report ─▶ cs-issue-analyze ─▶ cs-issue-fix │ issues/ │ - ─▶ cs-code-review ✦Gate │ - └──────────────┘ - - ▸ 事件：代码腐化（beta） ┌──────────────┐ - cs-refactor / cs-refactor-ff ─▶ cs-code-review ✦Gate│ refactors/ │ - └──────────────┘ - - ▸ 事件：目标驱动 ┌──────────────┐ - cs-goal ──▶ grill 起点报告 ─▶ 自主 impl/验证/迭代 │ goals/ │ - ─▶ subagent 功能验收 └──────────────┘ -═══════════════════════════════════════════════════════════════════════ - │ - ┌───────────────────┴───────────────────┐ - ▼ 任意阶段觉得"这个值得记下来"都能触发 ▼ 阶段/里程碑结束触发 -═══════════════════════════════════════════════════════════════════════ - 横切层 · 知识沉淀 & 文档整理 -─────────────────────────────────────────────────────────────────────── - cs-keep ──▶ .codestable/compound/YYYY-MM-DD-{slug}.md - 纯 markdown，无 frontmatter，grep 检索 - 下一次 cs-feat-design / cs-issue-analyze 会回头 grep 复用 - - cs-note ──▶ .codestable/attention.md（碎片约定：flag / 路径 / 别名） - - cs-docs-neat ──▶ 同步 .codestable/、README/docs、CLAUDE.md / AGENTS.md - 防止文档与代码脱节 -═══════════════════════════════════════════════════════════════════════ +cs +└── cs-onboard + ├── cs-req / cs-domain + ├── cs-epic # 用户侧大需求入口，内部暂用 roadmap 存储 + ├── cs-goal + ├── cs-brainstorm + ├── cs-feat -> cs-code-review + ├── cs-issue -> cs-code-review + ├── cs-refactor -> cs-code-review + ├── cs-docs + └── cs-keep / cs-note / cs-docs-neat ``` **怎么读这张图：** -- **纵向是层次**，不是严格的时间顺序——长效档案层会反复被刷新，规划层只在大需求时进入。 -- **✦Gate 是显式阻断点**：design-review / code-review / qa 三道 Gate 各自产出报告，有 blocking 发现时流程不能向前，必须回到对应 impl 修复后重新过 Gate。 -- **第 3 层是事件入口**：来了新需求走 feature 流，发现 bug 走 issue 流，发现腐化走 refactor 流，目标驱动走 goal 流。 -- **横切层是飞轮**：任何流程跑完发现"这事值得记下来"都可以触发 `cs-keep` 沉淀，沉淀的产物又会被下一次同类工作读到；`cs-docs-neat` 在里程碑收尾时统一整理文档防止漂移。 +- `cs` 只做轻量分诊到主入口，不再把用户导向阶段技能。 +- `cs-feat` / `cs-issue` / `cs-refactor` 是连续编排入口，会按仓库事实恢复阶段，并在 design、review、QA、accept 等 checkpoint 停下等用户确认。 +- `cs-epic` 负责大需求规划和 goal 执行包；第一版内部仍使用 `.codestable/roadmap/`，不批量迁移历史产物。 +- `cs-code-review` 是横切 gate；`cs-docs-neat` 是阶段收尾整理器；`cs-docs` 只写对外指南和 API 参考。 +- 旧阶段技能是长期兼容入口，历史用户可以继续调用，但新文档和新提示词应使用主入口。 完整示意图另见 [WORKFLOW.md](./WORKFLOW.md)。 @@ -360,7 +261,7 @@ CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动** │ │ ├── adrs/ │ │ └── {capability}.md │ │ -│ ├── roadmap/ # 路线图（"接下来打算怎么走"） +│ ├── roadmap/ # Epic 内部规划层（历史路径暂不迁移） │ │ └── {slug}/ │ │ ├── {slug}-roadmap.md # 主文档：背景 / 拆解 / 排期 │ │ ├── {slug}-items.yaml # 机器可读子 feature 清单，acceptance 回写状态 @@ -377,12 +278,12 @@ CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动** │ ├── features/ # 特性流程聚合根 │ │ └── YYYY-MM-DD-{slug}/ # 一个 feature 一个目录 │ │ ├── {slug}-brainstorm.md # 可选（cs-brainstorm 产出） -│ │ ├── {slug}-design.md # 方案（cs-feat-design） +│ │ ├── {slug}-design.md # 方案（cs-feat design 阶段） │ │ ├── {slug}-checklist.yaml # 推进清单（impl 跑、accept 回写） │ │ ├── {slug}-design-review.md # 人审前方案审查 │ │ ├── {slug}-review.md # 实现后代码审查 │ │ ├── {slug}-qa.md # 代码审查后 QA gate -│ │ └── {slug}-acceptance.md # 验收报告（cs-feat-accept） +│ │ └── {slug}-acceptance.md # 验收报告（cs-feat acceptance 阶段） │ │ │ ├── issues/ # 问题流程聚合根 │ │ └── YYYY-MM-DD-{slug}/ @@ -419,15 +320,15 @@ CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动** - `requirements/` 是**长效档案**（能力愿景 + 领域术语 CONTEXT.md + 拍板决策 adrs/），`roadmap/` 是**规划层**（接下来怎么走），两者刻意分开。 - `features/` `issues/` `refactors/` 用 `YYYY-MM-DD-{slug}/` 一个目录装齐所有相关 spec，不交叉。 - `compound/` 是**唯一**的知识沉淀目录，纯 markdown 无 frontmatter，靠 `grep -r` 检索——好写好搜。 -- `reference/` 是 `cs-onboard` 从技能包复制过来的；要改共享口径，改 `plugins/codestable/skills/cs-onboard/reference/` 模板，新项目 onboard 自动带上新版。 +- `.codestable/reference/` 是 `cs-onboard` 从技能包 `plugins/codestable/skills/cs-onboard/references/` 复制过来的；要改共享口径，改 skill 包内模板，新项目 onboard 自动带上新版。 ### 硬约束 -> Skill 是独立安装单元，运行时**每个 skill 只能看到自己包内的文件**。A 技能的 SKILL.md 里写 `B-skill/reference/xxx.md` 这种引用在运行时**根本读不到**。 +> 普通阶段规则不要从一个 skill 直接引用另一个 skill 的深层 `references/xxx.md`。阶段厚规则应放在主入口自己的 `references/` 下，或由 `cs-onboard` 释放到项目 `.codestable/reference/`。 > -> 跨 skill 共享的参考文档必须走"工作项目"这一层：由 `cs-onboard` 从技能包复制到项目的 `.codestable/reference/`，其他 skill 用项目相对路径读取。 +> 兼容入口是唯一例外：它只读取同级主入口的 `SKILL.md` 进入主协议，不直接读取主入口的深层 reference。 -要改共享口径，改 `plugins/codestable/skills/cs-onboard/reference/` 下的模板，新项目 onboard 时带上新版本。 +要改共享口径，改 `plugins/codestable/skills/cs-onboard/references/` 下的模板，新项目 onboard 时带上新版本。 完整目录说明和跨 skill 引用约束见 [WORKFLOW.md](./WORKFLOW.md)。 diff --git a/SKILL_CATALOG.en.md b/SKILL_CATALOG.en.md index 6d93286..1d81d29 100644 --- a/SKILL_CATALOG.en.md +++ b/SKILL_CATALOG.en.md @@ -1,33 +1,36 @@ # CodeStable Skill Catalog +Main entries accept optional stage / mode arguments (for example `/cs-feat qa`, `/cs-refactor ff`, `/cs-docs api auth-endpoints`). Arguments are only intent hints; repository facts always win. + +## Recommended Main Entries + | Group | Skill | Purpose | |---|---|---| -| Root entry | `cs` | Unified entry that introduces the system and routes open-ended intents to the right `cs-*` skill | -| Onboard | `cs-onboard` | Bring CodeStable into a new repo or one with scattered docs | -| Requirement and domain | `cs-req` | Curate and accumulate raw requirement docs | -| Requirement and domain | `cs-domain` | Maintain the domain model: `.codestable/requirements/CONTEXT.md` glossary + `adrs/` decision records + single/multi-context topology | -| Roadmap | `cs-roadmap` | Plan big work up front: high-level design, interface contracts, sub-feature breakdown | -| Roadmap | `cs-roadmap-review` | Independent planning review gate before human roadmap approval | -| Roadmap | `cs-roadmap-impl-goal` | Turn an approved roadmap into a runnable goal that executes impl / review / QA / accept per feature | -| Goal-driven | `cs-goal` | Goal-driven autonomous iteration: given a start point and desired end state, iterate until accepted; artifacts land in `.codestable/goals/` | -| Discussion entry | `cs-brainstorm` | Triage fuzzy ideas: direct design, feature brainstorm, or roadmap | -| Feature flow | `cs-feat` | Sub-flow entry for new features | -| Feature flow | `cs-feat-design` | Draft `{slug}-design.md` as the single input for what follows | -| Feature flow | `cs-feat-design-review` | Independent feature design review gate before human approval | -| Feature flow | `cs-feat-impl` | Code in the order the design lays out | -| Feature flow | `cs-code-review` | Read-only code review gate after implementation | -| Feature flow | `cs-feat-qa` | QA verification gate after code review; optional independent runner | -| Feature flow | `cs-feat-accept` | Verify implementation and close the loop; optional read-only auditor | -| Feature flow | `cs-feat-ff` | Ultra-light lane: no design, no phases, direct implementation | -| Issue flow | `cs-issue` | Sub-flow entry for issue fixing | -| Issue flow | `cs-issue-report` | Turn a problem into a reproducible, traceable report | -| Issue flow | `cs-issue-analyze` | Find root cause, assess risk, propose options | -| Issue flow | `cs-issue-fix` | Targeted fix, verification, and fix-note | -| Refactor flow | `cs-refactor` | Beta main refactor flow | -| Refactor flow | `cs-refactor-ff` | Beta light refactor lane | -| Knowledge sink | `cs-keep` | Sink freshly found pitfalls, tricks, decisions, and research into `.codestable/compound/` as plain markdown, retrieved via grep | -| Knowledge sink | `cs-note` | Append one-line startup notes to `.codestable/attention.md` | -| Explore and docs | `cs-audit` | Audit code for bug, security, performance, maintainability, and architecture risks | -| Explore and docs | `cs-doc-tutorial` | Write outward-facing developer guides | -| Explore and docs | `cs-doc-api` | Generate reference docs for public library surfaces | -| Explore and docs | `cs-docs-neat` | Reconcile `.codestable/`, README/docs, `CLAUDE.md` / `AGENTS.md`, and agent memory at phase close | +| Root | `cs` | Lightweight triage to the right main entry | +| Onboarding | `cs-onboard` | Install CodeStable into a new or previously informal repository | +| Requirements and domain | `cs-req` | Capture capability intent documents | +| Requirements and domain | `cs-domain` | Maintain domain terms, ADRs, and context topology | +| Epic | `cs-epic` | Large-demand entry: planning, review, child feature design, goal package | +| Goal | `cs-goal` | Autonomous iteration from a defined start state to accepted end state | +| Brainstorm | `cs-brainstorm` | Triage unclear ideas into feature, epic, or brainstorm notes | +| Feature flow | `cs-feat` | End-to-end feature entry: design, review, impl, code review, QA, accept | +| Issue flow | `cs-issue` | End-to-end issue entry: report, analyze, fix, review | +| Refactor flow | `cs-refactor` | Behavior-preserving refactor entry with standard and fastforward modes | +| Cross-cutting review | `cs-code-review` | Read-only implementation review gate | +| Audit | `cs-audit` | Scan for bugs, security, performance, maintainability, and architecture drift | +| Knowledge | `cs-keep` | Capture lessons, tricks, decisions, and research in `.codestable/compound/` | +| Knowledge | `cs-note` | Append short startup-critical notes to `.codestable/attention.md` | +| External docs | `cs-docs` | Write or update developer guides, user guides, and API references | +| Docs hygiene | `cs-docs-neat` | Sync `.codestable/`, README/docs, agent entry files, and memory | + +## Long-Term Compatibility Entries + +These skill names remain usable, but they only enter the corresponding main workflow and do not maintain independent rules. + +| Compatibility group | Skills | Enters | +|---|---|---| +| Feature | `cs-feat-design`, `cs-feat-design-review`, `cs-feat-impl`, `cs-feat-qa`, `cs-feat-accept`, `cs-feat-ff` | Matching `cs-feat` stage or mode | +| Issue | `cs-issue-report`, `cs-issue-analyze`, `cs-issue-fix` | Matching `cs-issue` stage | +| Refactor | `cs-refactor-ff` | `cs-refactor` fastforward mode | +| Docs | `cs-doc-tutorial`, `cs-doc-api` | `cs-docs` tutorial / api mode | +| Epic | `cs-roadmap`, `cs-roadmap-review`, `cs-roadmap-impl-goal` | `cs-epic` planning / review / goal-package stage | diff --git a/SKILL_CATALOG.md b/SKILL_CATALOG.md index d32344c..cb19c29 100644 --- a/SKILL_CATALOG.md +++ b/SKILL_CATALOG.md @@ -1,33 +1,36 @@ # CodeStable 技能目录 +主入口调用时可带阶段 / 模式参数（如 `/cs-feat qa`、`/cs-refactor ff`、`/cs-docs api 认证接口`）。参数只是意图提示，仓库事实始终优先。 + +## 推荐主入口 + | 分组 | 技能 | 用途 | |---|---|---| -| 根入口 | `cs` | 统一入口，介绍体系并把开放式诉求路由到正确的 `cs-*` 子技能 | -| 接入 | `cs-onboard` | 把 CodeStable 接入到一个新仓库或已有零散文档的仓库 | -| 需求与领域 | `cs-req` | 整理和沉淀原始需求文档 | -| 需求与领域 | `cs-domain` | 维护领域模型：`.codestable/requirements/CONTEXT.md` 术语表 + `adrs/` 决策记录 + 单/多 context 拓扑 | -| 路线图 | `cs-roadmap` | 为大需求做事前规划：概设、接口契约、子 feature 拆解 | -| 路线图 | `cs-roadmap-review` | roadmap 人工确认前的独立规划审查 gate | -| 路线图 | `cs-roadmap-impl-goal` | 把已确认 roadmap 编排成可直接运行的 goal，逐个 feature 执行 impl / review / QA / accept | -| 目标驱动 | `cs-goal` | 目标驱动的自主迭代：给定起点与期望终态，自动迭代到验收通过，产物落 `.codestable/goals/` | -| 讨论入口 | `cs-brainstorm` | 想法模糊时分诊：直接 design、进入 feature brainstorm，或移交 roadmap | -| 特性流程 | `cs-feat` | 新特性子流程入口 | -| 特性流程 | `cs-feat-design` | 起草 `{slug}-design.md` 作为后续唯一输入 | -| 特性流程 | `cs-feat-design-review` | feature design 人工确认前的独立方案审查 gate | -| 特性流程 | `cs-feat-impl` | 按 design 的推进顺序写代码 | -| 特性流程 | `cs-code-review` | 实现完成后的只读代码审查 gate | -| 特性流程 | `cs-feat-qa` | 代码审查通过后的 QA 验证 gate，可用独立 runner 辅助 | -| 特性流程 | `cs-feat-accept` | 对照 design 核对实现并完成验收闭环，可用只读 auditor 复核 | -| 特性流程 | `cs-feat-ff` | 超轻量通道：不写 design、不分阶段，直接实现 | -| 问题流程 | `cs-issue` | 问题修复子流程入口 | -| 问题流程 | `cs-issue-report` | 把问题落成可复现、可追溯的 report | -| 问题流程 | `cs-issue-analyze` | 找根因、评估修复风险、给方案 | -| 问题流程 | `cs-issue-fix` | 定点修复、验证并写 fix-note | -| 重构流程 | `cs-refactor` | beta 重构主流程 | -| 重构流程 | `cs-refactor-ff` | beta 轻量重构通道 | -| 知识沉淀 | `cs-keep` | 把刚发现的坑、技巧、决策、调研统一沉淀到 `.codestable/compound/`，纯 markdown，靠 grep 检索 | -| 知识沉淀 | `cs-note` | 把一两行启动必读的项目注意事项追加到 `.codestable/attention.md` | -| 探索与文档 | `cs-audit` | 主动审计代码中的 bug 隐患、安全、性能、可维护性和架构偏离 | -| 探索与文档 | `cs-doc-tutorial` | 编写对外开发者指南 | -| 探索与文档 | `cs-doc-api` | 为库的公开表面生成参考文档 | -| 探索与文档 | `cs-docs-neat` | 阶段收尾时同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 | +| 根入口 | `cs` | 轻量分诊，只把开放式诉求路由到主入口 | +| 接入 | `cs-onboard` | 把 CodeStable 接入新仓库或已有零散文档仓库 | +| 需求与领域 | `cs-req` | 整理和沉淀能力愿景文档 | +| 需求与领域 | `cs-domain` | 维护领域模型、术语表、ADR 和多 context 拓扑 | +| Epic | `cs-epic` | 大需求端到端入口：规划、review、子 feature design、goal 包 | +| 目标驱动 | `cs-goal` | 给定起点与期望终态后自主迭代到验收 | +| 讨论入口 | `cs-brainstorm` | 想法模糊时分诊到 feature、epic 或 brainstorm note | +| 特性流程 | `cs-feat` | 新特性端到端入口：design、review、impl、code review、QA、accept | +| 问题流程 | `cs-issue` | 问题修复端到端入口：report、analyze、fix、review | +| 重构流程 | `cs-refactor` | 行为等价重构入口：标准模式或 fastforward mode | +| 横切审查 | `cs-code-review` | 实现完成后的只读代码审查 gate | +| 审计 | `cs-audit` | 主动扫描 bug、安全、性能、可维护性和架构偏离 | +| 知识沉淀 | `cs-keep` | 把坑点、技巧、决策、调研沉淀到 `.codestable/compound/` | +| 知识沉淀 | `cs-note` | 把一两行启动必读项目注意事项追加到 `.codestable/attention.md` | +| 对外文档 | `cs-docs` | 写或更新开发者指南、用户指南、API 参考 | +| 文档收尾 | `cs-docs-neat` | 阶段收尾时同步 `.codestable/`、README/docs、agent 入口和记忆 | + +## 长期兼容入口 + +这些技能名继续可用，但只转入对应主入口，不维护独立流程规则。 + +| 兼容组 | 技能 | 转入 | +|---|---|---| +| Feature | `cs-feat-design`, `cs-feat-design-review`, `cs-feat-impl`, `cs-feat-qa`, `cs-feat-accept`, `cs-feat-ff` | `cs-feat` 的对应阶段或模式 | +| Issue | `cs-issue-report`, `cs-issue-analyze`, `cs-issue-fix` | `cs-issue` 的对应阶段 | +| Refactor | `cs-refactor-ff` | `cs-refactor` 的 fastforward mode | +| Docs | `cs-doc-tutorial`, `cs-doc-api` | `cs-docs` 的 tutorial / api mode | +| Epic | `cs-roadmap`, `cs-roadmap-review`, `cs-roadmap-impl-goal` | `cs-epic` 的 planning / review / goal-package 阶段 | diff --git a/WORKFLOW.en.md b/WORKFLOW.en.md index daeb309..1c7b3f2 100644 --- a/WORKFLOW.en.md +++ b/WORKFLOW.en.md @@ -2,33 +2,45 @@ ## Workflow Layers -CodeStable skills are layered and event-driven: +CodeStable is layered and event-driven. Daily use should start from main entries, not stage skill names: ```text cs └── cs-onboard ├── cs-req / cs-domain - ├── cs-roadmap - │ ├── cs-roadmap-review - │ └── cs-roadmap-impl-goal + ├── cs-epic + │ └── internally uses the roadmap storage model and goal package ├── cs-goal - ├── cs-feat-design -> cs-feat-design-review -> cs-feat-impl -> cs-code-review -> cs-feat-qa -> cs-feat-accept - ├── cs-issue-report -> cs-issue-analyze -> cs-issue-fix -> cs-code-review - ├── cs-refactor / cs-refactor-ff -> cs-code-review + ├── cs-brainstorm + ├── cs-feat -> cs-code-review + ├── cs-issue -> cs-code-review + ├── cs-refactor -> cs-code-review + ├── cs-docs └── cs-keep / cs-note / cs-docs-neat ``` -Vertical means layers, not strict time order. Long-lived archives are refreshed repeatedly; the roadmap layer is entered for large needs, and `cs-goal` is the goal-driven autonomous iteration entry that, given a start point and desired end state, iterates until accepted. Execution is event-driven: new capability goes to feature flow, bugs go to issue flow, and code rot goes to refactor flow; `cs-code-review` is the cross-cutting code review gate that all of feature / issue / refactor pass through to produce `{slug}-review.md`. The cross-cut layer is the knowledge flywheel: any flow sinks reusable experience into compound via `cs-keep`. -`cs-docs-neat` is the phase-close cleanup skill: it reconciles `.codestable/`, README/docs, `CLAUDE.md` / `AGENTS.md`, and agent memory without adding a new archive document type. +The vertical layout is layering, not strict time order. Long-lived records are refreshed repeatedly; `cs-epic` is only for large demands and still writes `.codestable/roadmap/` in the first version; `cs-goal` is the autonomous goal workflow. + +The event entries are `cs-feat` for new capability, `cs-issue` for bugs, `cs-refactor` for behavior-preserving cleanup, and `cs-docs` for outward documentation. `cs-code-review` remains the cross-cutting implementation review gate. + +The knowledge loop remains cross-cutting: any workflow can use `cs-keep`; milestone cleanup uses `cs-docs-neat` to sync `.codestable/`, README/docs, agent entry files, and memory. + +Old stage skills remain long-term compatibility entries: + +- Feature: `cs-feat-design` / `cs-feat-design-review` / `cs-feat-impl` / `cs-feat-qa` / `cs-feat-accept` / `cs-feat-ff` +- Issue: `cs-issue-report` / `cs-issue-analyze` / `cs-issue-fix` +- Refactor: `cs-refactor-ff` +- Docs: `cs-doc-tutorial` / `cs-doc-api` +- Epic: `cs-roadmap` / `cs-roadmap-review` / `cs-roadmap-impl-goal` ## Runtime Structure -After `/cs-onboard`, the project root gets `.codestable/`: +After `/cs-onboard`, the project root contains `.codestable/`: ```text .codestable/ -├── requirements/ # requirement docs + domain model: CONTEXT.md glossary + adrs/ ADRs -├── roadmap/ +├── requirements/ # requirements + domain model +├── roadmap/ # internal storage model for epic ├── goals/ ├── features/ ├── issues/ @@ -42,8 +54,8 @@ After `/cs-onboard`, the project root gets `.codestable/`: Key constraints: -- `requirements/` is a long-lived archive of current state: it holds requirement/capability docs as well as the cs-domain domain model — the `CONTEXT.md` glossary and `adrs/` decision records (split into `CONTEXT-MAP.md` plus per-context subdirectories under multi-context). -- `roadmap/` is the planning layer for large needs; `goals/` holds cs-goal start / iteration / acceptance artifacts. -- `features/`, `issues/`, and `refactors/` use `YYYY-MM-DD-{slug}/` to group one workflow run; `audits/` and `brainstorms/` likewise hold audit and brainstorm artifacts. -- `compound/` is the single knowledge sink; `cs-keep` writes pitfalls / tricks / decisions / research there as plain markdown files retrieved via grep. -- `reference/` is released by `cs-onboard`; cross-skill shared docs must go through project-local `.codestable/reference/`, not direct references to another skill package. +- `requirements/` stores long-lived current-state facts and the domain model. +- `roadmap/` remains the internal planning layer used by `cs-epic`; user-facing docs call it epic, but historical paths/doc_type are not migrated yet. +- `features/`, `issues/`, and `refactors/` use `YYYY-MM-DD-{slug}/` directories. +- `compound/` is the only knowledge compounding directory, written by `cs-keep`. +- `reference/` is released by `cs-onboard`; shared workflow conventions are read from project-local `.codestable/reference/`. diff --git a/WORKFLOW.md b/WORKFLOW.md index 9d1d1c2..b6fe04e 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -2,24 +2,36 @@ ## 工作流层次 -CodeStable 的技能是分层 + 事件驱动的： +CodeStable 的技能是分层 + 事件驱动的。日常使用主入口，不需要记阶段技能名： ```text cs └── cs-onboard ├── cs-req / cs-domain - ├── cs-roadmap - │ ├── cs-roadmap-review - │ └── cs-roadmap-impl-goal + ├── cs-epic + │ └── 内部使用 roadmap 存储模型和 goal 执行包 ├── cs-goal - ├── cs-feat-design -> cs-feat-design-review -> cs-feat-impl -> cs-code-review -> cs-feat-qa -> cs-feat-accept - ├── cs-issue-report -> cs-issue-analyze -> cs-issue-fix -> cs-code-review - ├── cs-refactor / cs-refactor-ff -> cs-code-review + ├── cs-brainstorm + ├── cs-feat -> cs-code-review + ├── cs-issue -> cs-code-review + ├── cs-refactor -> cs-code-review + ├── cs-docs └── cs-keep / cs-note / cs-docs-neat ``` -纵向是层次，不是严格时间顺序。长效档案层会反复刷新，规划层只在大需求时进入；`cs-goal` 是目标驱动的自主迭代入口，给定起点与期望终态后自动迭代到验收。第 3 层是事件入口：新需求走 feature，bug 走 issue，腐化走 refactor；`cs-code-review` 是横切代码审查 gate，feature / issue / refactor 链路都经它产 `{slug}-review.md`。横切层是知识飞轮：任何流程都可以把值得复用的经验经 `cs-keep` 沉淀到 compound。 -`cs-docs-neat` 是阶段收尾整理器，负责同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆，不新增沉淀文档类型。 +纵向是层次，不是严格时间顺序。长效档案层会反复刷新；`cs-epic` 只在大需求时进入，第一版内部仍写 `.codestable/roadmap/`；`cs-goal` 是目标驱动自主迭代入口。 + +第 3 层是事件入口：新需求走 `cs-feat`，bug 走 `cs-issue`，腐化走 `cs-refactor`，对外文档走 `cs-docs`。`cs-code-review` 是横切代码审查 gate，feature / issue / refactor 链路都经它产 `{slug}-review.md`。 + +横切层是知识飞轮：任何流程都可以把值得复用的经验经 `cs-keep` 沉淀到 compound；`cs-docs-neat` 在里程碑收尾时同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆。 + +旧阶段技能仍是长期兼容入口，但不再作为主路径展示： + +- Feature：`cs-feat-design` / `cs-feat-design-review` / `cs-feat-impl` / `cs-feat-qa` / `cs-feat-accept` / `cs-feat-ff` +- Issue：`cs-issue-report` / `cs-issue-analyze` / `cs-issue-fix` +- Refactor：`cs-refactor-ff` +- Docs：`cs-doc-tutorial` / `cs-doc-api` +- Epic：`cs-roadmap` / `cs-roadmap-review` / `cs-roadmap-impl-goal` ## 运行时结构 @@ -28,7 +40,7 @@ cs ```text .codestable/ ├── requirements/ # 需求文档 + 领域模型：CONTEXT.md 术语表 + adrs/ ADR -├── roadmap/ +├── roadmap/ # epic 的内部历史存储模型 ├── goals/ ├── features/ ├── issues/ @@ -42,8 +54,8 @@ cs 关键约束： -- `requirements/` 是长效档案，记现状：既存需求/能力文档，也存 cs-domain 的领域模型——`CONTEXT.md` 术语表与 `adrs/` 决策记录（多 context 时再拆 `CONTEXT-MAP.md` + 各子 context 子目录）。 -- `roadmap/` 是规划层，描述大需求接下来怎么走；`goals/` 存 cs-goal 的目标启动 / 迭代 / 验收产物。 -- `features/`、`issues/`、`refactors/` 用 `YYYY-MM-DD-{slug}/` 聚合单次流程产物；`audits/`、`brainstorms/` 同理存审计与头脑风暴产物。 -- `compound/` 是唯一知识沉淀目录，由 `cs-keep` 把坑 / 技巧 / 决策 / 调研统一写成纯 markdown 文件，靠 grep 检索。 -- `reference/` 由 `cs-onboard` 释放共享口径；跨 skill 共享文档必须通过项目内 `.codestable/reference/`，不能从一个 skill 直接引用另一个 skill 包内文件。 +- `requirements/` 是长效档案，记现状：既存需求/能力文档，也存 cs-domain 的领域模型。 +- `roadmap/` 是 `cs-epic` 第一版继续复用的内部规划层；用户文档叫 epic，历史路径/doc_type 暂不迁移。 +- `features/`、`issues/`、`refactors/` 用 `YYYY-MM-DD-{slug}/` 聚合单次流程产物。 +- `compound/` 是唯一知识沉淀目录，由 `cs-keep` 写纯 markdown 文件，靠 grep 检索。 +- `reference/` 由 `cs-onboard` 释放共享口径；跨工作流共享约定优先读项目内 `.codestable/reference/`。 diff --git a/plugins/codestable/skills/cs-brainstorm/SKILL.md b/plugins/codestable/skills/cs-brainstorm/SKILL.md index 3ee0818..fcb1102 100644 --- a/plugins/codestable/skills/cs-brainstorm/SKILL.md +++ b/plugins/codestable/skills/cs-brainstorm/SKILL.md @@ -23,10 +23,10 @@ brainstorm 是"讨论层"统一入口。 | case | 规模 | 用户状态 | 产物 | |---|---|---|---| -| **case 1：已经够清楚** | 不限 | 一句话能说清做什么 / 为谁 / 怎么算成功 / 不做什么 | 不落盘，直接 `cs-feat-design` | -| **case 2：小需求** | 单 feature | 知道要解决什么问题，对解法 / 边界还摇摆 | `.codestable/features/{feature}/{slug}-brainstorm.md` → `cs-feat-design` | -| **case 3：大需求，拆解 ready** | 多 feature | 心里已有大致模块划分，想直接做拆解和接口契约 | 不落盘，移交 `cs-roadmap` | -| **case 4：大需求，想 grill** | 多 feature | 还不想拆——想先 grill、发散、产生想法存着 | `.codestable/brainstorms/{slug}/brainstorm.md` → 之后 `cs-roadmap` 读到 | +| **case 1：已经够清楚** | 不限 | 一句话能说清做什么 / 为谁 / 怎么算成功 / 不做什么 | 不落盘，直接进 `cs-feat` design 阶段 | +| **case 2：小需求** | 单 feature | 知道要解决什么问题，对解法 / 边界还摇摆 | `.codestable/features/{feature}/{slug}-brainstorm.md` → `cs-feat` design 阶段 | +| **case 3：大需求，拆解 ready** | 多 feature | 心里已有大致模块划分，想直接做拆解和接口契约 | 不落盘，移交 `cs-epic` | +| **case 4：大需求，想 grill** | 多 feature | 还不想拆——想先 grill、发散、产生想法存着 | `.codestable/brainstorms/{slug}/brainstorm.md` → 之后 `cs-epic` 读到 | 判错 case 不是灾难——**允许升降级**。case 2 聊着发现范围越聊越大切 case 3/4，case 3 聊着发现需要先 grill 切 case 4，case 4 grill 完可以直接拆切 case 3，当场切换出口。 @@ -114,7 +114,7 @@ brainstorm 是"讨论层"统一入口。 1. **是事实问题不是偏好问题**——某 API 实际行为 / 库是否真支持 / 性能特征是否成立，不是"哪种风格更好" 2. **结果会改变方向**——验出来不管成败，讨论都能收敛 -3. **成本可控**——你判断 5-30 分钟内能搭出能跑的东西。超过这个量该走 `cs-feat-ff` 直接做或拆成正式 feature +3. **成本可控**——你判断 5-30 分钟内能搭出能跑的东西。超过这个量该走 `cs-feat` fastforward mode 直接做或拆成正式 feature 提议格式：**"这块靠想不准，我做个最小 demo 验一下 {要验的事}，5-10 分钟，OK 吗？"** 用户秒过 / 拒绝即可。 @@ -151,11 +151,11 @@ case 1 / case 3 也能借这个动作（不强求落 brainstorm note），逻辑 **信号**：一句话能说出做什么 / 为谁 / 怎么算成功 / 不做什么；聊两句核心行为 / 成功标准都对上。 **处理**： -1. 告诉用户"这块你已经想清楚了：{AI 一句话复述}。建议直接 `cs-feat-design`——brainstorm 对你没增量" +1. 告诉用户"这块你已经想清楚了：{AI 一句话复述}。建议直接进 `cs-feat` design 阶段——brainstorm 对你没增量" 2. **看聊过程有没有非琐碎技术决策**——讨论了具体库选型 / Schema / 接口形态 / 跨模块约定，落一份精简 brainstorm（只填"已敲定的设计点"那节）让 design 直接读到不必重讨；纯方向确认没聊技术细节就裸退不落盘 3. 停下来等用户触发 design -**退出**："直接触发 `cs-feat-design` 从零写 design"（不落盘）；轻量落盘则"下一步 `cs-feat-design` 会读到 `{路径}` 不必重述" +**退出**："直接触发 `cs-feat` 从零写 design"（不落盘）；轻量落盘则"下一步 `cs-feat` design 阶段会读到 `{路径}` 不必重述" --- @@ -180,20 +180,20 @@ case 1 / case 3 也能借这个动作（不强求落 brainstorm note），逻辑 文档模板见同目录 `reference.md` 的"feature brainstorm 模板"。frontmatter 字段口径跟 design / acceptance 共用一组，看 `shared-conventions.md` 第 1 节。 -**退出**：如果只是轻确认，主动问"这块够清楚了可以进 design 吗？"；如果需要解释方案 / 代价 / 默认后果，先在 feature 目录写 `approval-report.md` 再让 owner 确认。确认后落盘。如果愿景（用户故事 / 痛点 / 边界）已经聊透了，提示用户可以先 `cs-req draft` 把愿景落成 requirement，design 会读到这份 req 做对齐。告诉用户"下一步 `cs-feat-design` 会读到 `{路径}`" +**退出**：如果只是轻确认，主动问"这块够清楚了可以进 design 吗？"；如果需要解释方案 / 代价 / 默认后果，先在 feature 目录写 `approval-report.md` 再让 owner 确认。确认后落盘。如果愿景（用户故事 / 痛点 / 边界）已经聊透了，提示用户可以先 `cs-req draft` 把愿景落成 requirement，design 会读到这份 req 做对齐。告诉用户"下一步 `cs-feat` design 阶段会读到 `{路径}`" --- -### case 3：大需求 → roadmap 直接拆 +### case 3：大需求 → epic 直接拆 **信号**：多 feature 规模，用户心里已有大致模块划分，能说出拆法，想直接做拆解和接口契约。 **处理**： -1. 告诉用户"听起来是多个 feature 的集合，单 feature 装不下。`cs-roadmap` 会做拆解和依赖梳理，我把讨论交给它" -2. 把已聊的信息汇总让 roadmap 接手不用重来：真问题 / 大致范围 / 已提到的可能子模块（一句话各一）；**聊到的跨模块接口形态、共享协议、技术选型一并列出**——这些是 roadmap "架构层详设"节的种子 -3. **不落盘**——`roadmap new` 自己建目录和主文档 +1. 告诉用户"听起来是多个 feature 的集合，单 feature 装不下。`cs-epic` 会做拆解和依赖梳理，我把讨论交给它" +2. 把已聊的信息汇总让 epic planning 接手不用重来：真问题 / 大致范围 / 已提到的可能子模块（一句话各一）；**聊到的跨模块接口形态、共享协议、技术选型一并列出**——这些是内部 roadmap 主文档"架构层详设"节的种子 +3. **不落盘**——`cs-epic` planning 自己建目录和主文档 -**退出**："移交给 `cs-roadmap`"（附聊到的要点汇总），不落盘 +**退出**："移交给 `cs-epic` planning 阶段"（附聊到的要点汇总），不落盘 --- @@ -201,16 +201,16 @@ case 1 / case 3 也能借这个动作（不强求落 brainstorm note），逻辑 **信号**：多 feature 规模，但用户说不清模块边界、想先发散探索——"帮我问问清楚"、"先把想法理一理存着"、"方向还乱，聊开了再说"。 -这是创意空间，不是设计文档。目标是产生可留存的想法、方向和洞察，供后续 roadmap 消费。 +这是创意空间，不是设计文档。目标是产生可留存的想法、方向和洞察，供后续 epic planning 消费。 **怎么聊**：启动 grill 档（见上节"对话节奏 > grill 档"），同时自由发散——聊方案、聊类比、聊技术可能性、聊限制。对话比 case 2 更开放，不急着收敛。 **升降级**： -- grill 完感觉够清楚了想直接拆 → case 3，落 brainstorm.md 后移交 roadmap +- grill 完感觉够清楚了想直接拆 → case 3，落 brainstorm.md 后移交 `cs-epic` - 聊着发现其实一个 feature 能装下 → case 2 - 聊着发现已经全清楚 → case 1 -**落盘**：用户说"先这样"/"差不多了"/"存一下"，或 AI 判断 grill 已到 3-5 轮上限，主动说"这块我先帮你落到 brainstorms 里，之后 roadmap 会读到"。 +**落盘**：用户说"先这样"/"差不多了"/"存一下"，或 AI 判断 grill 已到 3-5 轮上限，主动说"这块我先帮你落到 brainstorms 里，之后 `cs-epic` 会读到"。 路径：`.codestable/brainstorms/{slug}/` @@ -227,9 +227,9 @@ case 1 / case 3 也能借这个动作（不强求落 brainstorm note），逻辑 - 比 case 2 模板更自由——不要求"选定方向"，允许保留多个倾向 - 不需要"考虑过的方向"那种结构化对比——那是 design 前的事，这里只是创意记录 -**和 roadmap 的衔接**：`cs-roadmap` 启动时会搜 `.codestable/brainstorms/` 看有没有相关 brainstorm。如果有，roadmap 把 brainstorm 当输入材料读，不重复分诊直接拆。 +**和 epic 的衔接**：`cs-epic` planning 阶段启动时会搜 `.codestable/brainstorms/` 看有没有相关 brainstorm。如果有，内部 roadmap 主文档把 brainstorm 当输入材料读，不重复分诊直接拆。 -**退出**：落盘后告诉用户"想法存到 `{路径}` 了，准备好了就触发 `cs-roadmap`，它会读到这份脑暴记录"。如果 grill 过程中愿景（用户故事 / 痛点 / 边界）已经比较清楚了，提示用户可以先 `cs-req draft` 把愿景落成 requirement，后续 roadmap 拆解和 design 都有稳定对齐基准 +**退出**：落盘后告诉用户"想法存到 `{路径}` 了，准备好了就触发 `cs-epic`，它会读到这份脑暴记录"。如果 grill 过程中愿景（用户故事 / 痛点 / 边界）已经比较清楚了，提示用户可以先 `cs-req draft` 把愿景落成 requirement，后续 epic 拆解和 design 都有稳定对齐基准 --- diff --git a/plugins/codestable/skills/cs-brainstorm/reference.md b/plugins/codestable/skills/cs-brainstorm/reference.md index 41e4a03..25a9bc2 100644 --- a/plugins/codestable/skills/cs-brainstorm/reference.md +++ b/plugins/codestable/skills/cs-brainstorm/reference.md @@ -56,7 +56,7 @@ tags: [...] # {主题名} -> 创意空间 | {YYYY-MM-DD} | 下一步：cs-roadmap +> 创意空间 | {YYYY-MM-DD} | 下一步：cs-epic ## 出发点 {什么触发了这个想法 / 想解决什么问题 / 为什么觉得值得做} diff --git a/plugins/codestable/skills/cs-code-review/SKILL.md b/plugins/codestable/skills/cs-code-review/SKILL.md index 4485a48..4bf64ba 100644 --- a/plugins/codestable/skills/cs-code-review/SKILL.md +++ b/plugins/codestable/skills/cs-code-review/SKILL.md @@ -1,6 +1,7 @@ --- name: cs-code-review description: Code review gate。触发：实现完成后、QA/验收/commit 前审本轮 diff。 +argument-hint: "[git range 或范围说明，可空]" --- # cs-code-review @@ -20,15 +21,19 @@ description: Code review gate。触发：实现完成后、QA/验收/commit 前 | 来源 | 进入点 | spec 产物 | 通过后去向 | |---|---|---|---| -| `cs-feat-impl`（标准 feature） | impl 完成、QA 前 | design + checklist | `cs-feat-qa` | -| `cs-feat-ff`（feature 快速通道） | ff-note 落盘、commit 前 | ff-note + 用户原始需求 | 收尾提交 | -| `cs-issue-fix` | fix-note 落盘、commit 前 | report + analysis + fix-note | 收尾提交 | -| `cs-refactor` | apply-notes 完成、commit 前 | scan + refactor-design + checklist | 收尾提交 | -| `cs-refactor-ff` | 自证通过、commit 前 | 用户确认的重构范围 + 验证命令 | 收尾提交 | +| `cs-feat` implementation 阶段 | impl 完成、QA 前 | design + checklist | `cs-feat` QA 阶段 | +| `cs-feat` fastforward mode | ff-note 落盘、commit 前 | ff-note + 用户原始需求 | 收尾提交 | +| `cs-issue` fix 阶段 | fix-note 落盘、commit 前 | report + analysis + fix-note | 收尾提交 | +| `cs-refactor` standard mode | apply-notes 完成、commit 前 | scan + refactor-design + checklist | 收尾提交 | +| `cs-refactor` fastforward mode | 自证通过、commit 前 | 用户确认的重构范围 + 验证命令 | 收尾提交 | | ad-hoc / pre-merge | 用户要求 | 用户指定范围 / git range | 给结论 | **不是 `cs-audit`**：audit 主动扫一片代码找潜在问题；code review 只审当前变更范围。 +本次调用参数：$ARGUMENTS。非空且不是字面 `$ARGUMENTS` 时，按 ad-hoc 来源处理，参数即用户指定的 git range / 审查范围；仍需按「启动检查」核对范围内确有可归因改动。 + +ad-hoc 参数如果是 git range（如 `main..HEAD`、`origin/main...HEAD` 或一个 commit/ref），审查范围来自 `git diff {range}`，不要求工作区有未提交 diff。参数如果是文件路径、自然语言范围或 pre-merge 说明，则先解析为明确文件 / diff 来源；解析不清时先问清楚。 + --- ## 输入 @@ -39,7 +44,7 @@ description: Code review gate。触发：实现完成后、QA/验收/commit 前 - 来源的 spec 产物（feature 看 `{slug}-design.md` + `{slug}-checklist.yaml`；issue 看 report+analysis+fix-note；refactor 看 scan+refactor-design+checklist；ff / ad-hoc 看用户确认范围） - 实现完成汇报 / 最近实现记录（如果在对话里，按对话事实引用；如果已落文件，读文件） - `git status --short` -- `git diff`（有 staged diff 时也读 `git diff --cached`） +- `git diff`（有 staged diff 时也读 `git diff --cached`；ad-hoc git range 读 `git diff {range}`） - diff 涉及的人写代码文件和相邻关键调用点 - spec 指向的 architecture / requirement / roadmap 相关文档（只读，判断改动是否会影响归并；feature 即 design 第 4 节） - goal / gate 模式下的 evidence pack、gate results、DoD results；缺失时回 implementation gate 补证据，不现场猜测 @@ -53,9 +58,9 @@ description: Code review gate。触发：实现完成后、QA/验收/commit 前 先按「进入来源」表确认本轮来源，再做对应前置校验： -1. 来源的 spec 产物存在且已定稿——feature 看 `{slug}-design.md`（`doc_type=feature-design`、`status=approved`、`feature` 与目录一致）+ `{slug}-checklist.yaml`（`steps` 全 `done`）；issue 看 report+analysis+fix-note；refactor 看 scan+refactor-design+checklist；ff / ad-hoc 看用户确认范围。缺定稿 spec 时退回对应实现技能，不硬审。 +1. 来源的 spec 产物存在且已定稿——feature 看 `{slug}-design.md`（`doc_type=feature-design`、`status=approved`、`feature` 与目录一致）+ `{slug}-checklist.yaml`（`steps` 全 `done`）；issue 看 report+analysis+fix-note；refactor 看 scan+refactor-design+checklist；ff 看用户确认范围；ad-hoc 看用户指定范围 / git range。缺定稿 spec 时退回对应实现技能，不硬审。 2. goal / gate 模式下，先读取 `{slug}-evidence-pack.md`、`{slug}-gate-results.json` 和 `{slug}-dod-results.json`；缺失或 gate blocking 未解释时退回 implementation.before_review。 -3. 当前 diff 能看到本轮实现改动；完全没有代码或产物改动时退回来源实现技能。 +3. 流程来源必须在当前 unstaged / staged diff 或本轮提交范围里看到实现改动；ad-hoc git range 必须 `git diff {range}` 非空。ad-hoc range 审查允许工作区干净；非 range 且完全没有可归因改动时退回来源实现技能或请用户补范围。 4. 如果已有 `{slug}-review.md`： - `status: passed` 且 diff 未变化：提示按表进入「通过后去向」。 - `status: changes-requested` / `blocked`：读取旧 findings，确认是否处于 review-fix 后的复审。 @@ -63,107 +68,11 @@ description: Code review gate。触发：实现完成后、QA/验收/commit 前 --- -## 独立 Task agent reviewer（双环节） +## 独立 reviewer 编排 -本阶段是**双环节 review**，两个环节互补： +本阶段必须按 `references/independent-review/protocol.md` 执行双环节 review：环节 A 是独立 Task agent review（gate 必需），环节 B 是 OCR 行级扫描（装了就跑）。主 agent 只负责启动、等待、事实核验、合并和落盘，不把本地审查当成环节 A。 -| 环节 | 目的 | 是否 gate 必需 | -|---|---|---| -| **A 独立 Task agent review** | spec 视角整体审查，用**独立上下文**避免主 agent 确认偏误 | 是（gate 放行靠它） | -| **B OCR 行级扫描** | 行级 bug / 安全 / 代码模式扫描，补 A 的盲区 | 否（装了就跑，缺了降级） | - -**检测由主 agent 在运行时自检自己的工具**，不靠脚本猜环境——主 agent 最清楚自己手上有哪些工具。 - ---- - -### 环节 A：独立 Task agent review（gate 必需） - -主 agent 按 Task agent 选择规则启动独立 Task agent reviewer（优先 Paseo subagent，否则当前宿主原生 Codex/Claude Task/Agent；都不可用时按 local-only fallback 处理）： - -1. **有 `mcp__paseo__create_agent` 工具** → 用 Paseo subagent（**首选**：能换 provider，做到真正异构审查）。 - 先加载 / 读取 `paseo` skill 的当前说明并遵守其规则：读取 `~/.paseo/orchestration-preferences.json`，使用 `providers.audit`，不要硬编码 provider；文件缺失时用合理默认并在报告说明。 -2. **否则有当前宿主原生 Codex/Claude Task/Agent 工具** → 启动原生 Task agent。独立上下文同样达成；若同模型，在报告里记录降级和残余风险。 -3. **两者都没有** → 记 `local-only`，不能伪装启动。gate 默认不放行，需用户明确降级（见 `reviewer` 字段）。 - -独立 Task agent reviewer prompt（只给原始材料，不透露主 agent 的任何 review 结论）： - -```text -你是 CodeStable 本次改动的独立代码审查 agent。只读，不修改文件，不更新 checklist/design。 - -请读取： -- .codestable/attention.md -- {design_path} -- {checklist_path} -- {evidence_pack_path}、{gate_results_path}、{dod_results_path}（存在时） -- 当前 git status / git diff / staged diff -- diff 涉及的人写代码和相邻关键调用点 - -按严重度输出：blocking / important / nit / suggestion / learning / praise / residual-risk。 -每条 finding 必须有 file:line 或仓库事实证据、影响、建议修复边界。 -执行一次**对抗式审查**：假设本次实现里一定藏着一个生产 bug，主动构造反例，优先攻击 design 不一致、边界值、错误路径、状态转换、并发/时序、权限/数据隔离、持久化/回滚和测试假阳性。 -额外输出 Test And QA Focus：QA 必须重点复核的场景、建议新增或加强的测试、review 无法确认的点。 -不要写 {slug}-review.md；只把审查结果回传给主 agent。 -``` - ---- - -### 环节 B：OCR 行级扫描（装了就跑） - -主 agent 自检 `ocr` CLI 是否可用： - -```bash -which ocr && ocr llm test -``` - -可用则自动调用（不需要用户显式要求），用 `--background` 传入 spec 摘要提升质量： - -```bash -ocr review --audience agent --background "{feature slug / 目标 / 本次改动范围}" -``` - -**OCR 只能审本轮 scope，不能用裸 workspace 模式发现 scope。**`ocr review` 默认会审 staged + unstaged + **untracked**；Roadmap 多 feature 连续执行时，历史 dirty/untracked 会让 OCR 越扫越大。调用规则： - -1. 先建立 `current_scope_files`：优先取 scope-gate / evidence pack 的 `changed_files`，否则取 `{feature-base}..HEAD` 或实现汇报中的本轮文件。 -2. 已提交 diff → 用 `ocr review --audience agent --from {feature-base} --to HEAD`。 -3. 未提交 diff → 只有 `git status --short` 的所有非 ignored 路径都属于 `current_scope_files`，才可裸跑 `ocr review`；否则记 `skipped-scope-ambiguous`，改为本地行级审查 `current_scope_files`。 -4. 合并 OCR finding 前，**丢弃**命中以下路径的 finding，无论 OCR 是否扫到—— - - `.codestable/`（CodeStable 自己的 spec / 工具产物，永远不是行级代码审查对象） - - 任何 `.` 开头的目录（`.git/`、`.claude/`、`.venv/` 等） - - `.gitignore` 命中的文件（`git check-ignore ` 为真） - 未被 `.gitignore` 忽略、且属于 `current_scope_files` 的 untracked 新增文件必须被本轮 review 覆盖。 - -OCR 的 High / Medium / Low 映射到 cs-code-review 严重度后合并： - -| OCR 优先级 | 映射规则 | -|---|---| -| High | 有仓库事实支撑 → `blocking`/`important`；证据不足 → `residual-risk` | -| Medium | `nit` 或 `suggestion` | -| Low | 丢弃（视为噪音），不进入报告 | - -OCR 不做 spec-fit 判断；mapping 后的 finding 必须经主 agent 本地事实核验才能升级为 `blocking`。`ocr` 未安装 / `ocr llm test` 失败 → 记 `not-available`，提示用户走 `cs-onboard` 的 open-code-review 段安装并配置；不阻塞本轮。注意 `ocr llm test` 超时（`context deadline exceeded`）多半是配置用了旧 `llm.*` 块——ocr v1.x 需用 `provider`/`providers` 体系，详见 onboard 段或 `codestable-doctor.py` 的 OCR 体检。 - ---- - -### 合并原则 - -A、B 两环节可并行启动。一旦某环节已启动，主 agent **不能在其返回前定稿 `{slug}-review.md`、给出 `passed` 或进入通过后去向**。 - -- 已启动的 reviewer 返回 → 逐条本地事实核验，去重，合并进报告，保留来源标注（`paseo` / `native-agent` / `ocr` / `local`）。 -- reviewer 失败 / 卡住 / 权限阻塞 → 报告 `status: blocked`，记录 `pending|failed|blocked` 和原因，让用户决定：重试、等待或明确降级。 -- 不要无限轮询；等通知或用户带回结果。 - -未经本地仓库事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级为 `blocking`。 - -**`reviewer` 字段（gate 锚点）**，按本轮实际完成的环节写： - -| 值 | 含义 | gate | -|---|---|---| -| `subagent+ocr` | 环节 A（Task agent）+ 环节 B 都完成（理想） | 放行 | -| `subagent` | 环节 A 完成，OCR 不可用 / 跳过 | 放行 | -| `ocr` | 仅 OCR，缺 Task agent review | 需 override | -| `self` | 两环节都缺 | 需 override | - -gate 默认要求 `subagent` 或 `subagent+ocr`；`ocr` 和 `self` 需配 `CODESTABLE_ALLOW_SELF_REVIEW_FALLBACK=1` 才放行。OCR 不能替代环节 A——目的不同（A 是 spec 隔离审查，B 是行级扫描）。 +进入审查流程第 2 步前先读取该 reference；没有读取它就不能启动 reviewer，也不能写 `reviewer` 字段。 ## 审查流程 @@ -176,11 +85,8 @@ gate 默认要求 `subagent` 或 `subagent+ocr`；`ocr` 和 `self` 需配 `CODES ### 2. 独立审查合并 -- 主 agent 自检工具：是否有 `mcp__paseo__create_agent` / 原生 Codex/Claude Task/Agent 工具，`which ocr` 是否可用。 -- 环节 A（独立 Task agent，Paseo subagent 优先→原生 Task agent）和环节 B（OCR）可并行启动，互不等待。 -- 本地可以先做整体审查草稿，但最终 verdict 必须等所有已启动 reviewer 返回后才能定稿。 -- 每环节返回后：逐条本地事实核验，OCR 结果按 High/Medium/Low 映射严重度，能复现 / 有证据才采纳；证据不足只写 residual-risk。 -- 某环节失败 / 卡住：不要默默降级；报告该环节 `failed|blocked`，交给用户决定重试或明确降级。 +- 按 `references/independent-review/protocol.md` 自检工具并启动环节 A / 环节 B；启动条件、OCR scope 规则、严重度映射和降级处理都以该 protocol 为准。 +- 本地可以先做整体审查草稿，但最终 verdict 必须等所有已启动 reviewer 返回、逐条本地事实核验合并后才能定稿。 - 报告里保留来源：标注每条 finding 来自哪个 reviewer（`paseo` / `native-agent` / `ocr` / `local`）。 ### 3. 整体审查 @@ -217,7 +123,7 @@ gate 默认要求 `subagent` 或 `subagent+ocr`；`ocr` 和 `self` 需配 `CODES - `changes-requested`：有 blocking，或 important 多到会影响验收可信度。 - `blocked`：缺少关键输入、diff 归因无法判断、设计/实现状态不满足 review 前置条件，或本轮已启动独立 Task agent reviewer 但结果仍 pending / failed / blocked 且用户尚未确认降级。 -**`reviewer` 字段（gate 锚点）**：`{slug}-review.md` 的 frontmatter `reviewer` 决定下游 worktree / commit / finish gate 是否放行，按「独立 Task agent reviewer（双环节）」实际完成情况写 `subagent+ocr` / `subagent` / `ocr` / `self`（语义见上节表）。任一已启动环节仍 pending / failed / blocked 时不定稿 `passed`，也不写 `subagent`。 +**`reviewer` 字段（gate 锚点）**：`{slug}-review.md` 的 frontmatter `reviewer` 决定下游 worktree / commit / finish gate 是否放行，按 `references/independent-review/protocol.md` 的实际完成情况写 `subagent+ocr` / `subagent` / `ocr` / `self`。任一已启动环节仍 pending / failed / blocked 时不定稿 `passed`，也不写 `subagent`。 --- @@ -245,7 +151,7 @@ gate 默认要求 `subagent` 或 `subagent+ocr`；`ocr` 和 `self` 需配 `CODES ## review-fix 衔接 -下一步去向按「进入来源」表确定（feature 来源即 review-fix→`cs-feat-impl`、通过→`cs-feat-qa`；issue/refactor/ff 各回对应实现技能与提交收尾）。 +下一步去向按「进入来源」表确定（feature 来源即 review-fix→`cs-feat` implementation 阶段、通过→`cs-feat` QA 阶段；issue/refactor/ff 各回对应主入口阶段或提交收尾）。 如果有 `blocking`： @@ -261,7 +167,7 @@ gate 默认要求 `subagent` 或 `subagent+ocr`；`ocr` 和 `self` 需配 `CODES 如果没有 blocking，且 important 已处理或被明确接受： - 报告 `status: passed`。 -- 告诉用户下一步是「进入来源」表的通过后去向（feature→`cs-feat-qa`）。 +- 告诉用户下一步是「进入来源」表的通过后去向（feature→`cs-feat` QA 阶段）。 --- @@ -277,7 +183,7 @@ gate 默认要求 `subagent` 或 `subagent+ocr`；`ocr` 和 `self` 需配 `CODES - [ ] 已写来源 spec 目录下的 `{slug}-review.md`（feature 即 `.codestable/features/{feature}/{slug}-review.md`）。 - [ ] `status: passed` 时 frontmatter `reviewer` 已按双环节实际完成写 `subagent+ocr` / `subagent`（或确属无 Task agent 能力的 `ocr` / `self` fallback）——这是下游 gate 的放行锚点。 - [ ] 有 blocking 时没有进入下游，而是指向来源实现技能的 review-fix。 -- [ ] 无 blocking 时明确告诉用户「进入来源」表的通过后去向（feature→`cs-feat-qa`）。 +- [ ] 无 blocking 时明确告诉用户「进入来源」表的通过后去向（feature→`cs-feat` QA 阶段）。 --- diff --git a/plugins/codestable/skills/cs-code-review/references/independent-review/protocol.md b/plugins/codestable/skills/cs-code-review/references/independent-review/protocol.md new file mode 100644 index 0000000..ca35eb7 --- /dev/null +++ b/plugins/codestable/skills/cs-code-review/references/independent-review/protocol.md @@ -0,0 +1,101 @@ +# Independent Review Protocol + +code review 是**双环节 review**，两个环节互补： + +| 环节 | 目的 | 是否 gate 必需 | +|---|---|---| +| A 独立 Task agent review | spec 视角整体审查，用独立上下文避免主 agent 确认偏误 | 是（gate 放行靠它） | +| B OCR 行级扫描 | 行级 bug / 安全 / 代码模式扫描，补 A 的盲区 | 否（装了就跑，缺了降级） | + +检测由主 agent 在运行时自检自己的工具，不靠脚本猜环境。主 agent 最清楚自己手上有哪些工具。 + +--- + +## 环节 A：独立 Task agent review（gate 必需） + +主 agent 按 Task agent 选择规则启动独立 reviewer（优先 Paseo subagent，否则当前宿主原生 Codex/Claude Task/Agent；都不可用时按 local-only fallback 处理）： + +1. **有 `mcp__paseo__create_agent` 工具** → 用 Paseo subagent（首选：能换 provider，做到真正异构审查）。 + 先加载 / 读取 `paseo` skill 的当前说明并遵守其规则：读取 `~/.paseo/orchestration-preferences.json`，使用 `providers.audit`，不要硬编码 provider；文件缺失时用合理默认并在报告说明。 +2. **否则有当前宿主原生 Codex/Claude Task/Agent 工具** → 启动原生 Task agent。独立上下文同样达成；若同模型，在报告里记录降级和残余风险。 +3. **两者都没有** → 记 `local-only`，不能伪装启动。gate 默认不放行，需用户明确降级（见 `reviewer` 字段）。 + +独立 Task agent reviewer prompt（只给原始材料，不透露主 agent 的任何 review 结论）： + +```text +你是 CodeStable 本次改动的独立代码审查 agent。只读，不修改文件，不更新 checklist/design。 + +请读取： +- .codestable/attention.md +- {design_path} +- {checklist_path} +- {evidence_pack_path}、{gate_results_path}、{dod_results_path}（存在时） +- 当前 git status / git diff / staged diff +- diff 涉及的人写代码和相邻关键调用点 + +按严重度输出：blocking / important / nit / suggestion / learning / praise / residual-risk。 +每条 finding 必须有 file:line 或仓库事实证据、影响、建议修复边界。 +执行一次对抗式审查：假设本次实现里一定藏着一个生产 bug，主动构造反例，优先攻击 design 不一致、边界值、错误路径、状态转换、并发/时序、权限/数据隔离、持久化/回滚和测试假阳性。 +额外输出 Test And QA Focus：QA 必须重点复核的场景、建议新增或加强的测试、review 无法确认的点。 +不要写 {slug}-review.md；只把审查结果回传给主 agent。 +``` + +--- + +## 环节 B：OCR 行级扫描（装了就跑） + +主 agent 自检 `ocr` CLI 是否可用： + +```bash +which ocr && ocr llm test +``` + +可用则自动调用（不需要用户显式要求），用 `--background` 传入 spec 摘要提升质量： + +```bash +ocr review --audience agent --background "{feature slug / 目标 / 本次改动范围}" +``` + +**OCR 只能审本轮 scope，不能用裸 workspace 模式发现 scope。**`ocr review` 默认会审 staged + unstaged + untracked；Roadmap 多 feature 连续执行时，历史 dirty/untracked 会让 OCR 越扫越大。调用规则： + +1. 先建立 `current_scope_files`：优先取 scope-gate / evidence pack 的 `changed_files`，否则取 `{feature-base}..HEAD` 或实现汇报中的本轮文件。 +2. 已提交 diff → 用 `ocr review --audience agent --from {feature-base} --to HEAD`。 +3. 未提交 diff → 只有 `git status --short` 的所有非 ignored 路径都属于 `current_scope_files`，才可裸跑 `ocr review`；否则记 `skipped-scope-ambiguous`，改为本地行级审查 `current_scope_files`。 +4. 合并 OCR finding 前，**丢弃**命中以下路径的 finding，无论 OCR 是否扫到： + - `.codestable/`（CodeStable 自己的 spec / 工具产物，永远不是行级代码审查对象） + - 任何 `.` 开头的目录（`.git/`、`.claude/`、`.venv/` 等） + - `.gitignore` 命中的文件（`git check-ignore ` 为真） + 未被 `.gitignore` 忽略、且属于 `current_scope_files` 的 untracked 新增文件必须被本轮 review 覆盖。 + +OCR 的 High / Medium / Low 映射到 cs-code-review 严重度后合并： + +| OCR 优先级 | 映射规则 | +|---|---| +| High | 有仓库事实支撑 → `blocking`/`important`；证据不足 → `residual-risk` | +| Medium | `nit` 或 `suggestion` | +| Low | 丢弃（视为噪音），不进入报告 | + +OCR 不做 spec-fit 判断；mapping 后的 finding 必须经主 agent 本地事实核验才能升级为 `blocking`。`ocr` 未安装 / `ocr llm test` 失败 → 记 `not-available`，提示用户走 `cs-onboard` 的 open-code-review 段安装并配置；不阻塞本轮。注意 `ocr llm test` 超时（`context deadline exceeded`）多半是配置用了旧 `llm.*` 块：ocr v1.x 需用 `provider`/`providers` 体系，详见 onboard 段或 `codestable-doctor.py` 的 OCR 体检。 + +--- + +## 合并与 reviewer 字段 + +A、B 两环节可并行启动。一旦某环节已启动，主 agent **不能在其返回前定稿 `{slug}-review.md`、给出 `passed` 或进入通过后去向**。 + +- 已启动的 reviewer 返回 → 逐条本地事实核验，去重，合并进报告，保留来源标注（`paseo` / `native-agent` / `ocr` / `local`）。 +- reviewer 失败 / 卡住 / 权限阻塞 → 报告 `status: blocked`，记录 `pending|failed|blocked` 和原因，让用户决定：重试、等待或明确降级。 +- 不要无限轮询；等通知或用户带回结果。 + +未经本地仓库事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级为 `blocking`。 + +`reviewer` 字段按本轮实际完成的环节写： + +| 值 | 含义 | gate | +|---|---|---| +| `subagent+ocr` | 环节 A（Task agent）+ 环节 B 都完成（理想） | 放行 | +| `subagent` | 环节 A 完成，OCR 不可用 / 跳过 | 放行 | +| `ocr` | 仅 OCR，缺 Task agent review | 需 override | +| `self` | 两环节都缺 | 需 override | + +gate 默认要求 `subagent` 或 `subagent+ocr`；`ocr` 和 `self` 需配 `CODESTABLE_ALLOW_SELF_REVIEW_FALLBACK=1` 才放行。OCR 不能替代环节 A：目的不同（A 是 spec 隔离审查，B 是行级扫描）。 diff --git a/plugins/codestable/skills/cs-code-review/references/report-template.md b/plugins/codestable/skills/cs-code-review/references/report-template.md index 73437ff..d1cc1a4 100644 --- a/plugins/codestable/skills/cs-code-review/references/report-template.md +++ b/plugins/codestable/skills/cs-code-review/references/report-template.md @@ -112,7 +112,7 @@ round: 1 ## 7. Verdict - Status: passed|changes-requested|blocked -- Next: 按「进入来源」表的通过后去向（feature→`cs-feat-qa`，其余→各自验收/提交） | 来源实现技能 review-fix | 等独立 Task agent reviewer 完成 / 用户确认降级后重跑本审查 | 补齐输入后重跑本审查 +- Next: 按「进入来源」表的通过后去向（feature→`cs-feat` QA 阶段，其余→各自验收/提交） | 来源实现技能 review-fix | 等独立 Task agent reviewer 完成 / 用户确认降级后重跑本审查 | 补齐输入后重跑本审查 ``` 没有某类 finding 时写 `none`，不要删除章节；下一轮复审要能对比。 diff --git a/plugins/codestable/skills/cs-doc-api/SKILL.md b/plugins/codestable/skills/cs-doc-api/SKILL.md index c04dd19..7c70548 100644 --- a/plugins/codestable/skills/cs-doc-api/SKILL.md +++ b/plugins/codestable/skills/cs-doc-api/SKILL.md @@ -1,143 +1,23 @@ --- name: cs-doc-api -description: API 参考文档。触发：写组件/函数/命令文档，或 acceptance 后新增公开接口。 +description: Docs API 兼容入口。旧调用保留；执行时转入 cs-docs 主流程的 api 模式。 --- # cs-doc-api -## 启动必读 +本技能是 `cs-docs` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_mode: api` -doc-tutorial 教你"怎么用 X 做 Y"，doc-api 告诉你"X 的每个零件长什么样、怎么配"。 +## 执行规则 -doc-tutorial 写错可能是表达不清，doc-api 写错就是错——信息源是源码本身，类型 / 默认值 / 签名都有唯一正确答案。**核心规则：不靠猜、不复制改名、每个条目独立读源码**。 +1. 按已安装 skill 名称加载 `cs-docs` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-docs` 主协议继续执行，并带上入口意图 `requested_mode: api`。 +3. 不要要求用户重新调用 `cs-docs`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 ---- +## 维护规则 -## 和 doc-tutorial 的对比 - -| | doc-tutorial | doc-api | -|---|---|---| -| 性质 | 任务导向（Tutorial / How-to） | 参考导向（Reference） | -| 回答 | "如何用 X 实现某个目标" | "X 的每个零件长什么样、怎么配" | -| 粒度 | 一个 feature / 一个场景一篇 | 一个条目一篇 | -| 信息源 | 方案 doc + 用户知识 | **源码本身**（类型 / 注释 / 默认值） | -| 数量级 | 几篇到十几篇 | 几十到上百篇 | - -互补：doc-tutorial 引用 doc-api 做详细参考（"完整 props 见 xxx"），doc-api 的"相关条目"链回 doc-tutorial。 - -## "条目（entry）" - -| 项目类型 | 条目粒度 | -|---|---| -| UI 组件库 | 一个组件 = 一个条目 | -| 工具函数库 | 一个模块或函数族 = 一个条目 | -| API Client | 一个 endpoint 族 = 一个条目 | -| CLI 工具 | 一个子命令 = 一个条目 | - -初始化阶段确认条目粒度后续保持一致——粒度变来变去清单和搜索都会乱。 - ---- - -## 涉及路径 - -doc-api 产物**不在 `.codestable/` 下**——API 参考是面向外部读者的可发布产物。 - -- 条目文档 → `docs/api/{slug}.md` -- 条目清单 → `docs/api/manifest.yaml` - -`docs/api/` 是默认约定，项目已有其他约定（`reference/` / `components/`）就以项目为准——开始前先确认。 - ---- - -## manifest / 模板 / 源码提取 - -参考材料在同目录 `reference.md`： - -- `manifest.yaml` 完整格式与 status 语义 -- 条目文档 frontmatter 和正文模板 -- 源码提取清单（接口签名、默认值、导出方式等） - -本技能正文只保留流程约束：**doc-api 以源码为事实源，不靠猜，不复制上一个条目改名**。 - ---- - -## 工作流 - -### Phase 1：初始化——扫描与清单 - -1. **确认项目类型 + 条目粒度 + 输出路径** -2. **扫描源码目录**——读 `source_root` 下文件结构，识别公开导出按逻辑分组 -3. **生成 `manifest.yaml`**——所有条目初始 `status: pending`；落盘后 `validate-yaml.py --file docs/api/manifest.yaml --yaml-only` 校验；展示给用户 review -4. **用户确认范围**——可标 `skipped`（内部实现）/ 调整分类 / 合并或拆分 - -### Phase 2：生成 - -#### 模式 A：单条目模式 - -适合 1-3 个条目或首次试跑确认质量。 - -选定条目 → 读 source_files → 按模板生成 → 用户 review → 落盘 → `validate-yaml.py --file {路径} --require doc_type --require entry --require status` → manifest 对应条目 `status: current` - -#### 模式 B：批量模式 - -适合清单里大量 `pending`。 - -1. **先出样板**——从清单选 2-3 个有代表性的条目（不同 category）走"读源码 → 提取 → 按模板生成"并落盘，状态先 `draft`（不直接进 current——批量模式下样板是"风格参考样本"等整体 review 一起转 current） -2. **用户确认质量标准**——review 这 2-3 篇确认模板 / 详略 / 风格。**这步不能跳**——50 篇全白写就因为用户想要的风格不一样 -3. **批量生成**——剩余 `pending` 逐条走"读源码 → 提取 → 生成"，可用 Task agent 并行；每条 `status: draft` -4. **整体 review**——批量完成展示概况（条目数 / 跳过数 / 待确认数）；review 前先 `validate-yaml.py --dir docs/api --require doc_type --require entry --require status` 批量校验 Markdown docs（目录模式默认不扫 `manifest.yaml`） -5. **确认落定**——用户确认后把样板和批量产出一起改 `status: current` - -**批量模式硬规则**： - -- **每个条目独立读源码**——即使批量也不允许复制上一个改名。两个看起来很像的接口经常有微妙差异 -- **样板确认不可跳** -- **源码结构特殊（动态导出 / 代码生成）暂标 `skipped` 加 note**——硬猜出来的文档比没文档更有害 - -### Phase 3：增量更新 - -代码变更后同步文档。三种入口任选： - -- `search-yaml.py` 搜 `status=outdated`——架构 check 或上次更新已标记的 -- 对比 `manifest.yaml` 里 `last_scanned` 之后变更的源码文件 -- `search-yaml.py --sort-by last_reviewed --order asc` 按最久没复核的排在前主动复核 - -重新读源码 → 对比已有文档 → 增量更新变化部分 → `validate-yaml.py` 校验 → `status: current` + `last_reviewed` 当天。 - ---- - -## 与其他工作流的关系 - -| 来源 | 关系 | -|---|---| -| `cs-feat-accept` | 验收后新增/修改库公开接口 → 推送"需要更新 doc-api 吗？" | -| `cs-doc-tutorial` | doc-tutorial 引用 doc-api 做详细参考；doc-api "相关条目"链回 doc-tutorial | -| `cs-feat-design` | 方案第 2 节可作 doc-api 补充信息源（**但以源码为准**） | -| `cs-keep` | doc-api "注意事项"与 compound 沉淀重合时交叉引用而不重复写 | - ---- - -## 退出条件 - -**Phase 1**：manifest.yaml 已落盘 + 用户已确认范围（含 skipped 理由）+ 粒度和输出路径已确认 - -**Phase 2 单条目**：条目按模板生成 + frontmatter 完整 + API 参考节信息来源于源码提取（非编造）+ 用户确认 + manifest 已更新 - -**Phase 2 批量**：样板（2-3 篇）已获用户确认 + 所有 pending 条目已生成或标 skipped + 用户做了整体 review + manifest 所有条目 status 已同步 - -**Phase 3**：outdated 条目已全部更新或确认不需更新 + manifest 无残留 outdated（除非用户明确暂缓） - ---- - -## 容易踩的坑 - -- 没扫清单就写文档——可能遗漏或重复 -- 没读源码就写 API 参考——doc-api 核心价值是准确反映源码 -- 复制上一个条目改名——必然漏掉微妙差异 -- 批量模式跳过样板确认——50 篇全白写 -- 把 spec 信息（不变量 / 测试约束）写进 doc-api——属于 `.codestable/` -- doc-api 和 doc-tutorial 内容高度重叠——其中一份定位有误 -- `manifest.yaml` 直接删行——改 `status: skipped` 并写 note -- 源码接口不存在却在文档写了——以源码为事实源不编造 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-docs` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-doc-tutorial/SKILL.md b/plugins/codestable/skills/cs-doc-tutorial/SKILL.md index 8b37a97..cc27861 100644 --- a/plugins/codestable/skills/cs-doc-tutorial/SKILL.md +++ b/plugins/codestable/skills/cs-doc-tutorial/SKILL.md @@ -1,158 +1,23 @@ --- name: cs-doc-tutorial -description: 对外指南文档。触发：写开发者/用户指南，或 acceptance 后需要任务导向 docs。 +description: Docs tutorial 兼容入口。旧调用保留；执行时转入 cs-docs 主流程的 tutorial 模式。 --- # cs-doc-tutorial -## 启动必读 +本技能是 `cs-docs` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_mode: tutorial` -代码解决问题，文档让别人能用它解决问题。spec 记录"做了什么、为什么这么做"，但下游开发者和终端用户不需要、也不应该读 spec——他们需要面向自己角色的、可发布的指南。doc-tutorial 就是从 spec 和代码出发写成读者真正能用的指南。 +## 执行规则 ---- +1. 按已安装 skill 名称加载 `cs-docs` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-docs` 主协议继续执行，并带上入口意图 `requested_mode: tutorial`。 +3. 不要要求用户重新调用 `cs-docs`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -## 两条轨道 +## 维护规则 -| 轨道 | 目标读者 | 典型内容 | 输出路径 | -|---|---|---|---| -| `dev-guide` | 贡献者、集成方、下游开发者 | 本地 setup、架构解说、API 说明、扩展方式 | `docs/dev/{slug}.md` | -| `user-guide` | 终端用户 | 功能概述、操作步骤、概念解释、常见问题 | `docs/user/{slug}.md` | - -**轨道选择从"谁读"出发**——同一个 feature 经常需要两份：API 变化进 dev-guide，对应的用户操作进 user-guide。 - -> 路径 `docs/dev/` 和 `docs/user/` 是默认约定，项目已有自己的 docs 结构就以项目为准——开始前先确认。 - ---- - -## 触发时机 - -| 情境 | 说明 | -|---|---| -| feature-acceptance 结束 | 主动推：方案第 2 节（接口契约）有变更问"需要更新 dev-guide 吗？"；第 1 节（用户可见行为）有变更问"需要更新 user-guide 吗？" | -| 用户主动触发 | "写文档"、"doc-tutorial"、"补一份开发者指南" | -| onboard 完成后 | 新仓库可触发补全基础文档骨架 | - -主动推送一句话即可，用户说"不用"就别再提——多次推会让用户觉得 AI 在加戏。 - ---- - -## 涉及路径 - -doc-tutorial 产物**不在 `.codestable/` 下**——指南是面向外部读者的可发布产物，和 spec 工件分开。 - -- dev-guide → `docs/dev/{slug}.md` -- user-guide → `docs/user/{slug}.md` - -文件命名 `{slug}.md`（英文小写连字符，**无日期前缀**）——指南持续更新按主题管理。 - -检索： - -``` -python .codestable/tools/search-yaml.py --dir docs/dev --filter doc_type=dev-guide --filter status=current -python .codestable/tools/search-yaml.py --dir docs/user --filter doc_type=user-guide --filter component={feature-slug} -``` - ---- - -## YAML frontmatter - -```yaml ---- -doc_type: dev-guide | user-guide -slug: {英文连字符} -component: {关联模块名或 feature slug} -status: draft | current | outdated -summary: {一句话描述涵盖什么} -tags: [] -last_reviewed: YYYY-MM-DD ---- -``` - -`status` 三态：`draft` 待 review；`current` 当前有效；`outdated` 对应代码已变文档没跟上（保留原文，标记后推送更新）。 - ---- - -## 文档格式 - -### dev-guide 正文结构 - -```markdown -## 概述 -一段话描述功能定位和适用场景。 - -## 前置依赖 -集成此模块所需的环境、依赖或配置（如有）。 - -## 快速上手 -最小可运行示例。代码优先文字辅助。 - -## 核心概念 -（可选）理解接口 / API / 模块行为所需的关键术语和设计决定。 - -## 接口参考 -主要 API / 配置选项 / 事件 / 钩子。表格或逐项列举。 - -## 常见场景 -2-4 个实际使用场景代码示例，覆盖 happy path 和常见边界。 - -## 已知限制与注意事项 -（可选）边界、性能考虑、已知 bug 绕过方式。 - -## 相关文档 -关联的 user-guide、方案 doc、相关 ADR 或外部参考。 -``` - -### user-guide 正文结构 - -```markdown -## 功能简介 -一段话描述功能是什么、解决什么问题。 - -## 前置条件 -（可选）使用前的前提（账号权限、需先完成的操作）。 - -## 如何使用 -步骤化操作。每步一行，关键操作配截图占位（`![描述](./assets/xxx.png)` 或注明"此处需截图"）。 - -## 常见问题 -Q: ... -A: ... - -## 相关功能 -（可选）关联功能跳转链接或说明。 -``` - ---- - -## 工作流步骤 - -1. **明确任务范围**——轨道（dev / user / 都要）+ 覆盖范围（新写还是更新）+ 信息来源（方案 doc 已有吗？同 component 已有 guide？需要读哪些代码？） -2. **收集输入**——读方案 doc（重点第 0 节术语、第 2 节接口契约、第 1 节用户可见行为）+ `search-yaml.py` 搜 docs/ 确认有无已有 guide。发现已有 guide 标 `outdated` → 任务定性为**更新** -3. **起草**——按对应轨道结构起草，frontmatter `status: draft`。约束：只写面向目标读者的内容——**不要把方案 doc 里"实现提示"或内部设计搬过来**；术语与方案 doc 第 0 节一致；代码示例必须来自实际代码不虚构接口 -4. **用户 review**——展示草稿，逐节确认覆盖范围 / 描述准确性 / 是否有读者看不懂的地方 -5. **落盘**——用户放行后：写入路径；`status: current` + `last_reviewed` 当天；更新已有文档时小修直接改，大改（结构重组 / 读者定位调整）先把旧文档 `status: outdated` 留作参考再新写一份 - ---- - -## 与其他工作流的关系 - -| 来源 | 关系 | -|---|---| -| `cs-feat-accept` | 验收后主动推：接口变更推 dev-guide，用户可见变更推 user-guide | -| `cs-feat-design` | 方案第 2 节是 dev-guide 主要信息源；第 1 节是 user-guide 主要信息源 | -| `cs-onboard` | 新仓库接入后可补全基础文档骨架 | -| `cs-keep` | dev-guide 引用的技术选型 / 用法示例若 compound 里已有沉淀，交叉引用而不重复写 | -| `cs-doc-api` | guide 引用 doc-api 条目做详细参考；doc-api 是零件参考，doc-tutorial 是任务教程 | - ---- - -## 容易踩的坑 - -- 把方案 doc 里"实现提示"原文搬进 dev-guide——那是内部 spec -- 没检查已有 guide 就新建——可能两份冲突 -- 写完 `status` 还是 `draft`——落盘必须改 `current` -- 代码已更新相关 guide 还是 `current`——应标 `outdated` 并推送更新 -- dev-guide 和 user-guide 内容高度重叠——其中一份定位有误 -- 用 guide 存放 spec 信息（不变量 / 测试约束 / 根因分析）——这类内容属于 `.codestable/` +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-docs` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-docs-neat/SKILL.md b/plugins/codestable/skills/cs-docs-neat/SKILL.md index 00c9b27..720957e 100644 --- a/plugins/codestable/skills/cs-docs-neat/SKILL.md +++ b/plugins/codestable/skills/cs-docs-neat/SKILL.md @@ -1,6 +1,7 @@ --- name: cs-docs-neat description: CodeStable 文档收尾。触发：阶段结束、整理文档、同步记忆、/sync、/neat。 +argument-hint: "[同步范围或关注点，可空]" --- # cs-docs-neat @@ -13,7 +14,9 @@ description: CodeStable 文档收尾。触发：阶段结束、整理文档、 不要把任务降级成“补几句文档”。在 AI 协作开发中，代码可以重写，但文档和记忆是跨会话、跨 agent 的桥梁。错误记忆会让下个 agent 基于错误前提动手；混乱 docs 会让接手者浪费时间重新推断系统。 -`cs-docs-neat` 不是 `cs-doc-tutorial`：`cs-doc-tutorial` 写单篇开发者 / 用户指南；`cs-docs-neat` 做阶段收尾的全局知识库卫生检查和同步。 +`cs-docs-neat` 不是 `cs-docs`：`cs-docs` 写单篇开发者 / 用户指南或 API 参考；`cs-docs-neat` 做阶段收尾的全局知识库卫生检查和同步。 + +本次调用参数：$ARGUMENTS。非空且不是字面 `$ARGUMENTS` 时，作为本轮同步的优先关注点；它只影响排序，不缩小 Phase 1 的机械式枚举范围。 --- @@ -269,11 +272,11 @@ du -sh docs .codestable 2>/dev/null | 技能 | 关系 | |---|---| | `cs-onboard` | 仓库未接入或需要迁移归档时先 onboard；本技能不负责搭骨架 | -| `cs-doc-tutorial` | 发现缺对外指南时建议或触发；已有指南过期可直接小修 | -| `cs-doc-api` | 公开 API 参考缺失或过期时建议 libdoc；本技能不批量生成 API 参考 | -| `cs-keep` / `cs-keep` / `cs-keep` / `cs-keep` | 发现稳定知识要归档时使用这些既有 doc_type | +| `cs-docs` tutorial mode | 发现缺对外指南时建议或触发；已有指南过期可直接小修 | +| `cs-docs` api mode | 公开 API 参考缺失或过期时建议；本技能不批量生成 API 参考 | +| `cs-keep`（doc_type：learning / trick / decision / explore） | 发现稳定知识要归档时沿用这些既有 doc_type，不新增本技能专属类型 | | `cs-note` | 发现一两行启动必读硬约束时，可建议或更新 attention | -| `cs-feat-accept` / `cs-issue-fix` / `cs-feat-ff` | 阶段结束后触发 neat 做全局同步 | +| `cs-feat` acceptance / fastforward、`cs-issue` fix | 阶段结束后触发 neat 做全局同步 | --- diff --git a/plugins/codestable/skills/cs-docs/SKILL.md b/plugins/codestable/skills/cs-docs/SKILL.md new file mode 100644 index 0000000..485b4b5 --- /dev/null +++ b/plugins/codestable/skills/cs-docs/SKILL.md @@ -0,0 +1,81 @@ +--- +name: cs-docs +description: Docs 主入口。触发：写/更新开发者指南、用户指南、API 参考；不包含 docs-neat 收尾整理。 +argument-hint: "[tutorial|api] [文档主题]" +--- + +# cs-docs + +## 启动必读 + +开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 + +`cs-docs` 是对外文档写作的唯一推荐入口，只覆盖开发者/用户指南和 API 参考。阶段收尾、知识库卫生、agent 入口同步仍走独立的 `cs-docs-neat`。 + +旧技能 `cs-doc-tutorial`、`cs-doc-api` 长期保留为兼容入口，只传入 `requested_mode`。 + +--- + +## 入口意图 + +本次调用参数：$ARGUMENTS + +意图来源按优先级：调用参数 > 兼容入口预设 > 用户话术。参数为空或未被替换（仍是字面 `$ARGUMENTS`）时跳过该来源；首个 token 命中 `tutorial` / `api` 则设为对应 `requested_mode`，其余文本作为文档主题。 + +用户没有明确文档类型时先判断目标读者和使用场景；仍不清楚就问用户选择。 + +--- + +## 模式边界 + +| 模式 | 产物 | 适用 | +|---|---|---| +| tutorial | 开发者指南 / 用户指南 | 教读者怎么完成一个任务 | +| api | API / 组件 / 命令参考 | 给读者查公开表面、参数、返回值、示例 | + +`cs-docs` 不做全局同步、不整理 `.codestable/`、不毕业 agent memory。发现这些需求时提示 `cs-docs-neat`。 + +--- + +## 状态机 + +启动后先扫既有文档和公开表面：`docs/`、`README*`、用户点名路径、相关源码导出/API/命令。按仓库事实恢复： + +| 仓库事实 | 下一步 | +|---|---| +| 用户要任务教程/使用指南，且没有对应 guide | 读取 `references/tutorial/protocol.md` 新建 | +| 已有 guide，但相关代码/spec 已变或 status 为 `outdated` | 读取 `references/tutorial/protocol.md` 更新 | +| 用户要 API/组件/命令参考，且无 manifest 或条目缺失 | 读取 `references/api/protocol.md` 初始化或补条目 | +| API manifest / 条目存在且有 `pending`、`draft` 或 `outdated` | 读取 `references/api/protocol.md` 生成或增量更新 | +| 目标文档已 `current` 且用户只要小改 | 做聚焦编辑，保持事实可追溯 | +| 诉求是全局同步、README/agent 入口/记忆整理 | 转 `cs-docs-neat` | + +用户说“继续写文档”时，也按文件和 frontmatter / manifest 状态判断，不靠聊天历史。 + +--- + +## Reference 加载 + +- tutorial：`references/tutorial/protocol.md` +- api：`references/api/protocol.md`，必要时 `references/api/reference.md` + +先读代码和既有文档，再按对应模式生成或更新文档。不要凭记忆写 API。 + +--- + +## 人工 checkpoint + +必须停下等用户明确确认的点： + +1. 新建文档前：目标读者、文档类型（tutorial / api）和落点路径。 +2. 覆盖或重写已有 `current` 文档前：确认旧内容确实过期，不是并行有效版本。 +3. 文档表述会改变 user-facing 契约或公开理解时：让用户确认口径后再落盘。 + +--- + +## 退出条件 + +- 文档目标读者、入口路径和状态已明确。 +- 新增/更新文档的 `status` 或 manifest 状态已落到 `draft` / `current` / `outdated` / `pending` / `skipped` 中的合法值。 +- 新增/更新的文档能从源码或现有项目事实追溯。 +- 需要同步 README、agent 入口或记忆时，明确提示后续运行 `cs-docs-neat`。 diff --git a/plugins/codestable/skills/cs-docs/references/api/protocol.md b/plugins/codestable/skills/cs-docs/references/api/protocol.md new file mode 100644 index 0000000..689fdf5 --- /dev/null +++ b/plugins/codestable/skills/cs-docs/references/api/protocol.md @@ -0,0 +1,134 @@ +# Docs API Reference Protocol + +doc-tutorial 教你"怎么用 X 做 Y"，doc-api 告诉你"X 的每个零件长什么样、怎么配"。 + +doc-tutorial 写错可能是表达不清，doc-api 写错就是错——信息源是源码本身，类型 / 默认值 / 签名都有唯一正确答案。**核心规则：不靠猜、不复制改名、每个条目独立读源码**。 + +--- + +## 和 doc-tutorial 的对比 + +| | doc-tutorial | doc-api | +|---|---|---| +| 性质 | 任务导向（Tutorial / How-to） | 参考导向（Reference） | +| 回答 | "如何用 X 实现某个目标" | "X 的每个零件长什么样、怎么配" | +| 粒度 | 一个 feature / 一个场景一篇 | 一个条目一篇 | +| 信息源 | 方案 doc + 用户知识 | **源码本身**（类型 / 注释 / 默认值） | +| 数量级 | 几篇到十几篇 | 几十到上百篇 | + +互补：doc-tutorial 引用 doc-api 做详细参考（"完整 props 见 xxx"），doc-api 的"相关条目"链回 doc-tutorial。 + +## "条目（entry）" + +| 项目类型 | 条目粒度 | +|---|---| +| UI 组件库 | 一个组件 = 一个条目 | +| 工具函数库 | 一个模块或函数族 = 一个条目 | +| API Client | 一个 endpoint 族 = 一个条目 | +| CLI 工具 | 一个子命令 = 一个条目 | + +初始化阶段确认条目粒度后续保持一致——粒度变来变去清单和搜索都会乱。 + +--- + +## 涉及路径 + +doc-api 产物**不在 `.codestable/` 下**——API 参考是面向外部读者的可发布产物。 + +- 条目文档 → `docs/api/{slug}.md` +- 条目清单 → `docs/api/manifest.yaml` + +`docs/api/` 是默认约定，项目已有其他约定（`reference/` / `components/`）就以项目为准——开始前先确认。 + +--- + +## manifest / 模板 / 源码提取 + +参考材料在同目录 `reference.md`： + +- `manifest.yaml` 完整格式与 status 语义 +- 条目文档 frontmatter 和正文模板 +- 源码提取清单（接口签名、默认值、导出方式等） + +本协议核心约束：**doc-api 以源码为事实源，不靠猜，不复制上一个条目改名**。 + +--- + +## 工作流 + +### Phase 1：初始化——扫描与清单 + +1. **确认项目类型 + 条目粒度 + 输出路径** +2. **扫描源码目录**——读 `source_root` 下文件结构，识别公开导出按逻辑分组 +3. **生成 `manifest.yaml`**——所有条目初始 `status: pending`；落盘后 `validate-yaml.py --file docs/api/manifest.yaml --yaml-only` 校验；展示给用户 review +4. **用户确认范围**——可标 `skipped`（内部实现）/ 调整分类 / 合并或拆分 + +### Phase 2：生成 + +#### 模式 A：单条目模式 + +适合 1-3 个条目或首次试跑确认质量。 + +选定条目 → 读 source_files → 按模板生成 → 用户 review → 落盘 → `validate-yaml.py --file {路径} --require doc_type --require entry --require status` → manifest 对应条目 `status: current` + +#### 模式 B：批量模式 + +适合清单里大量 `pending`。 + +1. **先出样板**——从清单选 2-3 个有代表性的条目（不同 category）走"读源码 → 提取 → 按模板生成"并落盘，状态先 `draft`（不直接进 current——批量模式下样板是"风格参考样本"等整体 review 一起转 current） +2. **用户确认质量标准**——review 这 2-3 篇确认模板 / 详略 / 风格。**这步不能跳**——50 篇全白写就因为用户想要的风格不一样 +3. **批量生成**——剩余 `pending` 逐条走"读源码 → 提取 → 生成"，可用 Task agent 并行；每条 `status: draft` +4. **整体 review**——批量完成展示概况（条目数 / 跳过数 / 待确认数）；review 前先 `validate-yaml.py --dir docs/api --require doc_type --require entry --require status` 批量校验 Markdown docs（目录模式默认不扫 `manifest.yaml`） +5. **确认落定**——用户确认后把样板和批量产出一起改 `status: current` + +**批量模式硬规则**： + +- **每个条目独立读源码**——即使批量也不允许复制上一个改名。两个看起来很像的接口经常有微妙差异 +- **样板确认不可跳** +- **源码结构特殊（动态导出 / 代码生成）暂标 `skipped` 加 note**——硬猜出来的文档比没文档更有害 + +### Phase 3：增量更新 + +代码变更后同步文档。三种入口任选： + +- `search-yaml.py` 搜 `status=outdated`——架构 check 或上次更新已标记的 +- 对比 `manifest.yaml` 里 `last_scanned` 之后变更的源码文件 +- `search-yaml.py --sort-by last_reviewed --order asc` 按最久没复核的排在前主动复核 + +重新读源码 → 对比已有文档 → 增量更新变化部分 → `validate-yaml.py` 校验 → `status: current` + `last_reviewed` 当天。 + +--- + +## 与其他工作流的关系 + +| 来源 | 关系 | +|---|---| +| `cs-feat` acceptance 阶段 | 验收后新增/修改库公开接口 → 推送"需要更新 doc-api 吗？" | +| `cs-docs` tutorial 模式 | doc-tutorial 引用 doc-api 做详细参考；doc-api "相关条目"链回 doc-tutorial | +| `cs-feat` design 阶段 | 方案第 2 节可作 doc-api 补充信息源（**但以源码为准**） | +| `cs-keep` | doc-api "注意事项"与 compound 沉淀重合时交叉引用而不重复写 | + +--- + +## 退出条件 + +**Phase 1**：manifest.yaml 已落盘 + 用户已确认范围（含 skipped 理由）+ 粒度和输出路径已确认 + +**Phase 2 单条目**：条目按模板生成 + frontmatter 完整 + API 参考节信息来源于源码提取（非编造）+ 用户确认 + manifest 已更新 + +**Phase 2 批量**：样板（2-3 篇）已获用户确认 + 所有 pending 条目已生成或标 skipped + 用户做了整体 review + manifest 所有条目 status 已同步 + +**Phase 3**：outdated 条目已全部更新或确认不需更新 + manifest 无残留 outdated（除非用户明确暂缓） + +--- + +## 容易踩的坑 + +- 没扫清单就写文档——可能遗漏或重复 +- 没读源码就写 API 参考——doc-api 核心价值是准确反映源码 +- 复制上一个条目改名——必然漏掉微妙差异 +- 批量模式跳过样板确认——50 篇全白写 +- 把 spec 信息（不变量 / 测试约束）写进 doc-api——属于 `.codestable/` +- doc-api 和 doc-tutorial 内容高度重叠——其中一份定位有误 +- `manifest.yaml` 直接删行——改 `status: skipped` 并写 note +- 源码接口不存在却在文档写了——以源码为事实源不编造 diff --git a/plugins/codestable/skills/cs-doc-api/reference.md b/plugins/codestable/skills/cs-docs/references/api/reference.md similarity index 88% rename from plugins/codestable/skills/cs-doc-api/reference.md rename to plugins/codestable/skills/cs-docs/references/api/reference.md index 89945e1..826fe87 100644 --- a/plugins/codestable/skills/cs-doc-api/reference.md +++ b/plugins/codestable/skills/cs-docs/references/api/reference.md @@ -1,6 +1,6 @@ # doc-api 参考模板 -本文件提供 `cs-doc-api` 使用的 manifest、条目文档模板和源码提取清单。 +本文件提供 `cs-docs` api 模式 使用的 manifest、条目文档模板和源码提取清单。 ## 1. `manifest.yaml` 格式 diff --git a/plugins/codestable/skills/cs-docs/references/tutorial/protocol.md b/plugins/codestable/skills/cs-docs/references/tutorial/protocol.md new file mode 100644 index 0000000..95ccc3e --- /dev/null +++ b/plugins/codestable/skills/cs-docs/references/tutorial/protocol.md @@ -0,0 +1,149 @@ +# Docs Tutorial Protocol + +代码解决问题，文档让别人能用它解决问题。spec 记录"做了什么、为什么这么做"，但下游开发者和终端用户不需要、也不应该读 spec——他们需要面向自己角色的、可发布的指南。doc-tutorial 就是从 spec 和代码出发写成读者真正能用的指南。 + +--- + +## 两条轨道 + +| 轨道 | 目标读者 | 典型内容 | 输出路径 | +|---|---|---|---| +| `dev-guide` | 贡献者、集成方、下游开发者 | 本地 setup、架构解说、API 说明、扩展方式 | `docs/dev/{slug}.md` | +| `user-guide` | 终端用户 | 功能概述、操作步骤、概念解释、常见问题 | `docs/user/{slug}.md` | + +**轨道选择从"谁读"出发**——同一个 feature 经常需要两份：API 变化进 dev-guide，对应的用户操作进 user-guide。 + +> 路径 `docs/dev/` 和 `docs/user/` 是默认约定，项目已有自己的 docs 结构就以项目为准——开始前先确认。 + +--- + +## 触发时机 + +| 情境 | 说明 | +|---|---| +| feature-acceptance 结束 | 主动推：方案第 2 节（接口契约）有变更问"需要更新 dev-guide 吗？"；第 1 节（用户可见行为）有变更问"需要更新 user-guide 吗？" | +| 用户主动触发 | "写文档"、"doc-tutorial"、"补一份开发者指南" | +| onboard 完成后 | 新仓库可触发补全基础文档骨架 | + +主动推送一句话即可，用户说"不用"就别再提——多次推会让用户觉得 AI 在加戏。 + +--- + +## 涉及路径 + +doc-tutorial 产物**不在 `.codestable/` 下**——指南是面向外部读者的可发布产物，和 spec 工件分开。 + +- dev-guide → `docs/dev/{slug}.md` +- user-guide → `docs/user/{slug}.md` + +文件命名 `{slug}.md`（英文小写连字符，**无日期前缀**）——指南持续更新按主题管理。 + +检索： + +``` +python .codestable/tools/search-yaml.py --dir docs/dev --filter doc_type=dev-guide --filter status=current +python .codestable/tools/search-yaml.py --dir docs/user --filter doc_type=user-guide --filter component={feature-slug} +``` + +--- + +## YAML frontmatter + +```yaml +--- +doc_type: dev-guide | user-guide +slug: {英文连字符} +component: {关联模块名或 feature slug} +status: draft | current | outdated +summary: {一句话描述涵盖什么} +tags: [] +last_reviewed: YYYY-MM-DD +--- +``` + +`status` 三态：`draft` 待 review；`current` 当前有效；`outdated` 对应代码已变文档没跟上（保留原文，标记后推送更新）。 + +--- + +## 文档格式 + +### dev-guide 正文结构 + +```markdown +## 概述 +一段话描述功能定位和适用场景。 + +## 前置依赖 +集成此模块所需的环境、依赖或配置（如有）。 + +## 快速上手 +最小可运行示例。代码优先文字辅助。 + +## 核心概念 +（可选）理解接口 / API / 模块行为所需的关键术语和设计决定。 + +## 接口参考 +主要 API / 配置选项 / 事件 / 钩子。表格或逐项列举。 + +## 常见场景 +2-4 个实际使用场景代码示例，覆盖 happy path 和常见边界。 + +## 已知限制与注意事项 +（可选）边界、性能考虑、已知 bug 绕过方式。 + +## 相关文档 +关联的 user-guide、方案 doc、相关 ADR 或外部参考。 +``` + +### user-guide 正文结构 + +```markdown +## 功能简介 +一段话描述功能是什么、解决什么问题。 + +## 前置条件 +（可选）使用前的前提（账号权限、需先完成的操作）。 + +## 如何使用 +步骤化操作。每步一行，关键操作配截图占位（`![描述](./assets/xxx.png)` 或注明"此处需截图"）。 + +## 常见问题 +Q: ... +A: ... + +## 相关功能 +（可选）关联功能跳转链接或说明。 +``` + +--- + +## 工作流步骤 + +1. **明确任务范围**——轨道（dev / user / 都要）+ 覆盖范围（新写还是更新）+ 信息来源（方案 doc 已有吗？同 component 已有 guide？需要读哪些代码？） +2. **收集输入**——读方案 doc（重点第 0 节术语、第 2 节接口契约、第 1 节用户可见行为）+ `search-yaml.py` 搜 docs/ 确认有无已有 guide。发现已有 guide 标 `outdated` → 任务定性为**更新** +3. **起草**——按对应轨道结构起草，frontmatter `status: draft`。约束：只写面向目标读者的内容——**不要把方案 doc 里"实现提示"或内部设计搬过来**；术语与方案 doc 第 0 节一致；代码示例必须来自实际代码不虚构接口 +4. **用户 review**——展示草稿，逐节确认覆盖范围 / 描述准确性 / 是否有读者看不懂的地方 +5. **落盘**——用户放行后：写入路径；`status: current` + `last_reviewed` 当天；更新已有文档时小修直接改，大改（结构重组 / 读者定位调整）先把旧文档 `status: outdated` 留作参考再新写一份 + +--- + +## 与其他工作流的关系 + +| 来源 | 关系 | +|---|---| +| `cs-feat` acceptance 阶段 | 验收后主动推：接口变更推 dev-guide，用户可见变更推 user-guide | +| `cs-feat` design 阶段 | 方案第 2 节是 dev-guide 主要信息源；第 1 节是 user-guide 主要信息源 | +| `cs-onboard` | 新仓库接入后可补全基础文档骨架 | +| `cs-keep` | dev-guide 引用的技术选型 / 用法示例若 compound 里已有沉淀，交叉引用而不重复写 | +| `cs-docs` api 模式 | guide 引用 doc-api 条目做详细参考；doc-api 是零件参考，doc-tutorial 是任务教程 | + +--- + +## 容易踩的坑 + +- 把方案 doc 里"实现提示"原文搬进 dev-guide——那是内部 spec +- 没检查已有 guide 就新建——可能两份冲突 +- 写完 `status` 还是 `draft`——落盘必须改 `current` +- 代码已更新相关 guide 还是 `current`——应标 `outdated` 并推送更新 +- dev-guide 和 user-guide 内容高度重叠——其中一份定位有误 +- 用 guide 存放 spec 信息（不变量 / 测试约束 / 根因分析）——这类内容属于 `.codestable/` diff --git a/plugins/codestable/skills/cs-epic/SKILL.md b/plugins/codestable/skills/cs-epic/SKILL.md new file mode 100644 index 0000000..e997f6d --- /dev/null +++ b/plugins/codestable/skills/cs-epic/SKILL.md @@ -0,0 +1,85 @@ +--- +name: cs-epic +description: Epic 主入口。触发：大需求/系统级能力/执行整个 epic；规划、review、feature design、goal 包。 +argument-hint: "[planning|review|goal-package] [大需求描述]" +--- + +# cs-epic + +## 启动必读 + +开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 + +`cs-epic` 是大需求端到端入口。用户文档统一叫 epic；为兼容历史产物，第一版内部目录、frontmatter 和工具仍使用 `roadmap`。 + +旧技能 `cs-roadmap`、`cs-roadmap-review`、`cs-roadmap-impl-goal` 长期保留为兼容入口，只传入 `requested_stage`。 + +--- + +## 入口意图 + +本次调用参数：$ARGUMENTS + +意图来源按优先级：调用参数 > 兼容入口预设 > 用户话术。参数为空或未被替换（仍是字面 `$ARGUMENTS`）时跳过该来源；首个 token 命中 `planning` / `review` / `goal-package` 则设为对应 `requested_stage`，其余文本作为大需求描述。 + +入口意图不覆盖仓库事实。已有 roadmap review 未通过时先修规划；已有 feature design 未确认时不生成 goal 包。 + +--- + +## 文件放哪儿 + +```text +.codestable/roadmap/{slug}/ +├── {slug}-roadmap.md +├── {slug}-items.yaml +├── {slug}-roadmap-review.md +├── goal-plan.md +├── goal-state.yaml +├── goal-protocol*.md +├── goal-audit.md +└── goal-features/ +``` + +普通子 feature 仍放 `.codestable/features/YYYY-MM-DD-{feature-slug}/`。 + +--- + +## 状态机 + +| 仓库事实 | 下一步 | +|---|---| +| 大需求未拆解 | 读取 `references/planning/protocol.md` | +| roadmap draft 无 passed review | 读取 `references/review/protocol.md` | +| roadmap review blocking / blocked | 回 planning 修订后重跑 review | +| roadmap review passed 但用户未确认 | 停下让用户确认 epic 规划 | +| roadmap 已确认，子 feature design 未完成 | 逐项进入 `cs-feat` design/design-review | +| 子 feature design-review passed 但未整体确认 | 停下让用户确认所有 design | +| 所有 design approved，goal 包未生成 | 读取 `references/goal/protocol.md` | +| goal 包已生成 | 输出可粘贴 `/goal` 指令并停止 | + +`cs-epic` 不自动执行 slash command。`/goal` 只能由用户触发。 + +--- + +## Reference 加载 + +- planning：`references/planning/protocol.md`，必要时 `references/planning/reference.md`、`references/planning/support/codebase-design.md` +- review：`references/review/protocol.md` +- goal-package：`references/goal/protocol.md`，并复制 `references/goal/support/protocol*.md` 和 `references/goal/support/goal-command-template.md` +- child feature：通过 `cs-feat` 主入口推进，不直接调用旧阶段技能 + +--- + +## 人工 checkpoint + +1. roadmap/epic planning review passed 后，用户确认规划。 +2. 所有子 feature design-review passed 后，用户统一确认 design。 +3. goal 包生成后，只输出 `/goal` 指令，不自动执行。 + +--- + +## 退出条件 + +- 规划、审查、子 feature design 和 goal 包状态能从仓库事实恢复。 +- 历史 `roadmap` 命名只作为内部兼容说明出现；用户主路径称为 epic。 +- 需要同步文档或记忆时提示 `cs-docs-neat`。 diff --git a/plugins/codestable/skills/cs-epic/references/goal/protocol.md b/plugins/codestable/skills/cs-epic/references/goal/protocol.md new file mode 100644 index 0000000..a9261b9 --- /dev/null +++ b/plugins/codestable/skills/cs-epic/references/goal/protocol.md @@ -0,0 +1,219 @@ +# Epic Goal Package Protocol + +## 目标 + +把一个大需求变成可审阅、可恢复、可自动推进的 CodeStable roadmap 执行包： + +1. 先按 `cs-epic` planning 阶段规范澄清需求并创建 / 更新一份 roadmap，运行 `cs-epic` review 阶段并处理到通过。 +2. 用户确认 roadmap 后，为 roadmap items 里的每个子 feature 进入 `cs-feat` design 阶段，生成 design + checklist，运行 `cs-feat` design-review 阶段并处理到通过。 +3. 用户确认所有 feature design 后，输出一条可直接粘贴的 `/goal` 指令。 +4. `/goal` 会话按顺序循环执行每个 feature：`cs-feat` implementation 阶段 → `cs-code-review` → 必要时 review-fix → `cs-feat` QA 阶段 → 必要时 qa-fix 后重跑 review/QA → `cs-feat` acceptance 阶段 → 更新状态 → 下一个 feature。 +5. 全部 feature 验收后，做整个 roadmap 的最终审计；只有审计通过才打印完成标记。 + +注意：不要把长任务正文塞进 `/goal` 参数。长协议和 feature 执行规格写入 roadmap 自己的目录，`/goal` 只引用这些文件和终止标记。 + +--- + +## 目录约定 + +**复用 `cs-epic` planning 阶段的目录，不创建独立顶层目录。** + +在现有 roadmap 目录下增加 goal 执行文件： + +```text +.codestable/roadmap/{slug}/ +├── {slug}-roadmap.md +├── {slug}-items.yaml +├── {slug}-roadmap-review.md +├── goal-plan.md # 本次 goal 执行总览：假设 / 风险 / feature 顺序 / 验证命令 +├── goal-state.yaml # goal 会话实时状态 +├── goal-protocol.md # 从 support/protocol*.md 复制并按 slug 落地 +├── goal-protocol-feature-loop.md +├── goal-protocol-gates.md +├── goal-protocol-audit.md +├── goal-audit.md # goal 会话结束前生成的最终 roadmap 审计报告 +└── goal-features/ + └── {feature-slug}.md # 每个 feature 的执行规格，指向 design/checklist +``` + +普通 feature 仍放在标准目录： + +```text +.codestable/features/{YYYY-MM-DD}-{feature-slug}/ +├── {feature-slug}-design.md +├── {feature-slug}-checklist.yaml +├── {feature-slug}-design-review.md +├── {feature-slug}-review.md # goal 执行时生成 +├── {feature-slug}-qa.md # goal 执行时生成 +└── {feature-slug}-acceptance.md # goal 执行时生成 +``` + +--- + +## 两次确认门禁 + +本协议必须按两次确认推进，不能跳过。 + +### 第一次确认：roadmap + +先完成 `cs-epic` planning 阶段的 new / update 流程，并通过人审前 review gate： + +- 澄清大需求目标、范围、明确不做、成功标准。 +- 读取 `.codestable/attention.md`、相关 requirements / architecture / compound / history features。 +- 写 `{slug}-roadmap.md` 和 `{slug}-items.yaml`。 +- 自查模块拆分、接口契约、依赖 DAG、最小闭环、safety net / polish / harden、验证入口、交付物、知识回写候选。 +- 运行 `cs-epic` review 阶段，如果有 blocking / blocked，先修订或等待 reviewer；不要把未通过 review gate 的 roadmap 给用户确认。 +- 把完整 roadmap + items.yaml + `{slug}-roadmap-review.md` 给用户 review。 + +只有用户明确确认 roadmap 后，才进入所有 feature design 阶段。 + +### 第二次确认：所有 feature design + +对 roadmap items 里的每个 planned 子 feature，按依赖顺序逐个完成 `cs-feat` design 阶段的候选设计阶段： + +- 创建 feature 目录。 +- 写 `{feature-slug}-design.md`，frontmatter 带 `roadmap` / `roadmap_item`，正文按 `.codestable/attention.md` 的报告语言落盘（默认中文）。 +- 写 `{feature-slug}-checklist.yaml`。 +- 运行 `cs-feat` design-review 阶段；Task agent 可用时每份 design-review 都必须有独立 reviewer 结果。批量生成多个 feature 不是 local-only 降级理由；有 blocking / blocked / pending 时先修订、等待 reviewer 或让用户明确授权降级，不进入用户二次确认。 +- 按现有 `cs-feat` design 阶段约定，把 items.yaml 对应条目更新为 `in-progress` 并填写 `feature` 字段。 +- design 必须包含：基线预检、必跑验证命令、交付物、验收场景证据类型、清洁度规则、可独立验证 steps。 + +这里把 `cs-feat` design 阶段普通模式里的单 feature 用户整体 review 推迟到本协议统一处理：每份 design 先保持 `draft`，不要逐个改 `approved`。全部 feature design 都写完且 design-review 都 passed 后，一次性给用户 review。用户可能反复修改任意一个 design；每次修改后同步更新 checklist，并对实质变化重跑 `cs-feat` design-review 阶段。只有用户明确确认所有 design 后，才输出 `/goal`。 + +用户确认所有 design 后，先把每份 `{feature-slug}-design.md` 的 frontmatter `status` 从 `draft` 改为 `approved`，再生成 goal 执行包。`cs-feat` implementation 阶段和 `cs-feat` acceptance 阶段都要求 design 已 approved；不要把 draft design 交给 goal 会话。 + +--- + +## 生成 goal 执行包 + +在 `.codestable/roadmap/{slug}/` 内写： + +### `goal-plan.md` + +包含： + +- roadmap 路径和 items.yaml 路径 +- feature 执行顺序 +- 每个 feature 的一句话交付物 +- 每个 feature 的性质：functional / non-functional / mixed +- roadmap 级核心验收路径：必须真实运行的用户 / API / CLI / 后端 / e2e / smoke 场景；没有则写 none，并说明为什么这是纯非功能性 roadmap +- 关键假设 +- Top 3 风险与缓解 +- 必跑验证命令集合 +- 最终聚合测试命令集合：roadmap 完成前必须重跑的 build / typecheck / lint / unit / integration / e2e / smoke；纯非功能性 roadmap 可用静态 / 一致性 / schema / 文档校验替代，但要写理由 +- 预检策略 +- DoD Policy、Gate Policy、Provider Policy +- Provider Policy 必须写明 archguard / meta-cc unavailable 记录 fallback，不自动阻塞；provider warning 需由 review / QA / audit 解释 +- 验证工具缺失时的恢复策略：只能补测试依赖、锁文件或既有 runner 配置，不能新增同名 shim 或伪造验证结果 +- 最终审计会核验的交付物类型 +- 最终审计必须运行 `codestable-goal-consistency-gate.py --roadmap {roadmap-path}` +- 最终审计会聚合 goal-evidence-summary、provider warnings、E/C/H summary 和 H-only core checks + +### `goal-state.yaml` + +生成前必须先探测 git 基线： + +1. 运行 `git rev-parse --is-inside-work-tree`。 +2. 返回 `true` 时，运行 `git rev-parse HEAD`，把得到的 SHA 写入 `baseline_ref`。 +3. 返回非 git 仓库时，`baseline_ref: no-git`。 +4. 在 git 仓库内但无法取得 HEAD 时，先停止并修复基线（例如还没有任何提交），不要写 `no-git` 伪装成非 git 仓库。 + +格式： + +```yaml +roadmap: "{slug}" +status: ready-to-dispatch +baseline_ref: "{git rev-parse HEAD 或 no-git}" +current_feature_index: 0 +features: + - slug: "{feature-slug}" + roadmap_item: "{feature-slug}" + feature_dir: ".codestable/features/YYYY-MM-DD-{feature-slug}" + design: ".codestable/features/YYYY-MM-DD-{feature-slug}/{feature-slug}-design.md" + checklist: ".codestable/features/YYYY-MM-DD-{feature-slug}/{feature-slug}-checklist.yaml" + review: ".codestable/features/YYYY-MM-DD-{feature-slug}/{feature-slug}-review.md" + qa: ".codestable/features/YYYY-MM-DD-{feature-slug}/{feature-slug}-qa.md" + acceptance: ".codestable/features/YYYY-MM-DD-{feature-slug}/{feature-slug}-acceptance.md" + status: pending +``` + +`current_feature_index` 是 **0-based**，指向 `features` 数组中下一个要处理的元素；第一个 feature 必须是 `0`。每个 feature accepted 后必须 scoped-commit 且确认工作树干净，再加 1。展示给用户的 `Feature: N/总数` 仍使用 1-based。roadmap item 若在执行前被标 `dropped`，不要写入 `goal-state.features`；已进入 `goal-state.features` 的条目必须走到 `accepted` 或回退修复。 + +### `goal-protocol*.md` + +从 `support/protocol.md`、`protocol-feature-loop.md`、`protocol-gates.md`、`protocol-audit.md` 复制到 roadmap 目录，并把 `{roadmap-slug}` / `{roadmap-path}` / `{roadmap-file}` / `{items-file}` 替换为本次实际值。不要替换 `` 这类运行时占位；它们必须保留给 goal 会话在每个 feature 边界填写。 + +`goal-protocol-gates.md` 是 Gate Policy 的运行时权威入口；`scope-gate`、`dod-runner`、`evidence-pack` 等具体脚本由 `cs-onboard` 安装到项目 `.codestable/tools/`。缺脚本时先刷新 onboard 骨架，不要把缺失脚本当作 gate passed。 + +### `goal-features/{feature-slug}.md` + +每个 feature 一份，包含： + +- 对应 roadmap item +- design / checklist / design-review / review / QA / acceptance 路径 +- 依赖项 +- feature 性质：functional / non-functional / mixed +- 核心运行路径：功能性 feature 必填；非功能性 feature 写 none + 替代证据 +- 必跑命令 +- Feature DoD、stage gates、gate 输入产物、失败恢复路径 +- 验收证据 +- 交付物 +- 清洁度规则 +- 失败恢复边界 + +--- + +## 自查 + +输出 `/goal` 前必须自查并修正： + +1. roadmap items 是否 DAG，无循环依赖。 +2. 每个 item 是否已有 design + checklist。 +3. roadmap review 是否存在且 `status: passed`，没有 unresolved blocking finding。 +4. 每个 item 是否已有 design-review 且 `status: passed`，没有 unresolved blocking finding，并记录已完成独立 reviewer 或用户明确降级。 +5. 每份 design 是否已 `status: approved`，且 frontmatter 的 `roadmap` / `roadmap_item` 与 items.yaml 一致。 +6. 每个 checklist step 是否可独立验证，且初始 `steps.status` 为 `pending`、`checks.status` 为 `pending`。 +7. 每个 feature 是否有必跑命令 / 基线风险 / 交付物 / 清洁度规则。 +8. 每个 goal-feature spec 是否写明 design-review / review / QA / acceptance 产物路径，以及 review blocking / QA failed 的返回路径。 +9. `goal-state.yaml` 是否能断点恢复，且 `current_feature_index` 使用 0-based 语义。 +10. `goal-plan.md` 是否写明 roadmap 级核心验收路径、最终聚合测试命令、非功能性替代证据策略、DoD Policy、Gate Policy、Provider Policy。 +11. 用户是否已明确确认 roadmap 和所有 feature design。 +12. `goal-protocol*.md` 是否都低于 300 行，且没有把 roadmap slug 误替换进 feature 标记；`Feature:` 行必须使用 `` 或真实当前 feature slug。 +13. 验证命令如果依赖外部测试工具，goal-plan / goal-feature spec 是否说明真实 runner 或依赖安装方式；不能通过新增 `pytest.py`、`jest`、`go` 等同名 shim 绕过。 +14. 最终审计是否能从仓库事实核验每个交付物，运行 goal consistency gate，并会落盘到 `{roadmap-path}/goal-audit.md`。 + +--- + +## 输出给用户的 goal 指令 + +确认通过后，读取 `support/goal-command-template.md`，替换 `{slug}`，打印一条 fenced `/goal`，然后停止。 + +只输出指令，不替用户执行；slash command 只能由用户粘贴触发。 + +--- + +## 完成判据 + +本阶段完成于：用户拿到可直接粘贴的 `/goal` 指令。 + +真正的 roadmap 完成由 goal 会话负责，必须满足： + +- 所有 goal-state features 状态为 `accepted` +- roadmap items 全部 `done` 或带理由 `dropped` +- 每个 feature 有 review 报告，且无 unresolved blocking findings +- 每个 feature 有 QA 报告，且无 unresolved failed / blocked items +- 每个 feature 有 acceptance 报告 +- `{roadmap-path}/goal-audit.md` 存在，记录最终聚合测试、roadmap 级核心验收路径、跳过项、re-verified / trust-prior 和结论 +- architecture / requirement / roadmap 回写完成 +- 最终审计通过 +- 已做 learning reflection：筛出 pitfall / knowledge 候选，并建议用户确认后再运行 `cs-keep` +- 已提示用户可运行 `cs-docs-neat`，同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 +- transcript 打印 `CS_ROADMAP_GOAL_COMPLETE` + +注意：goal 会话只自动做学习点反思和候选筛选，不自动写 `.codestable/compound/`。长期知识库归档必须由用户确认后触发 `cs-keep`，按它自己的查重、提炼、review、归档流程执行。 + +--- + +## 资源 + +写 `goal-protocol*.md` 时读取 `support/protocol.md`、`support/protocol-feature-loop.md`、`support/protocol-gates.md`、`support/protocol-audit.md`。输出 slash command 时读取 `support/goal-command-template.md`。 diff --git a/plugins/codestable/skills/cs-epic/references/goal/support/goal-command-template.md b/plugins/codestable/skills/cs-epic/references/goal/support/goal-command-template.md new file mode 100644 index 0000000..450fdd4 --- /dev/null +++ b/plugins/codestable/skills/cs-epic/references/goal/support/goal-command-template.md @@ -0,0 +1,7 @@ +# Roadmap Goal 指令模板 + +`cs-epic` goal 阶段在完成两次用户确认、写完 goal 执行包并自查通过后，按本模板输出 fenced `/goal`。替换 `{slug}`，保留 `{feature-slug}` 运行时占位。 + +```text +/goal "执行 CodeStable roadmap 目录 .codestable/roadmap/{slug} 下的 goal 执行包。先读取 goal-protocol.md、goal-protocol-feature-loop.md、goal-protocol-gates.md、goal-protocol-audit.md、goal-state.yaml、goal-plan.md；这是已由用户确认 roadmap 和全部 feature design 后的 goal 模式，按 goal-plan.md 的 Gate Policy 与 goal-protocol-gates.md 的 gate 接管规则执行。按 goal-state.yaml 的 features 顺序循环处理每个 feature：读取 goal-features/{feature-slug}.md、对应 design 和 checklist，进入 cs-feat implementation 阶段，再完成 cs-code-review；如果 review 有 blocking findings，按 review-fix 修复后重跑 cs-code-review；review passed 后进入 cs-feat QA 阶段；如果 QA failed / blocked，按 qa-fix 修复后重跑 cs-code-review 和 cs-feat QA 阶段；QA passed 后进入 cs-feat acceptance 阶段，并更新 goal-state.yaml 与 roadmap items。每个 feature 验证通过后打印 CS_ROADMAP_GOAL_FEATURE_DONE。所有 feature 完成后，按 goal-protocol-audit.md 做最终 roadmap 审计。只有当 CS_ROADMAP_GOAL_COMPLETE 出现在 transcript 中，且所有 feature 都已 review passed、QA passed 且 accept、最终审计通过、没有 CS_ROADMAP_GOAL_HANDOFF，本 goal 才算完成。" +``` diff --git a/plugins/codestable/skills/cs-roadmap-impl-goal/references/protocol-audit.md b/plugins/codestable/skills/cs-epic/references/goal/support/protocol-audit.md similarity index 100% rename from plugins/codestable/skills/cs-roadmap-impl-goal/references/protocol-audit.md rename to plugins/codestable/skills/cs-epic/references/goal/support/protocol-audit.md diff --git a/plugins/codestable/skills/cs-roadmap-impl-goal/references/protocol-feature-loop.md b/plugins/codestable/skills/cs-epic/references/goal/support/protocol-feature-loop.md similarity index 86% rename from plugins/codestable/skills/cs-roadmap-impl-goal/references/protocol-feature-loop.md rename to plugins/codestable/skills/cs-epic/references/goal/support/protocol-feature-loop.md index 1df0045..7b2fde2 100644 --- a/plugins/codestable/skills/cs-roadmap-impl-goal/references/protocol-feature-loop.md +++ b/plugins/codestable/skills/cs-epic/references/goal/support/protocol-feature-loop.md @@ -26,15 +26,15 @@ Evidence required: <证据列表> ## 2. 实现阶段 -必须显式使用 `$cs-feat-impl` 执行；禁止仅凭本协议摘要替代对应 skill。开始写代码前先打印： +必须显式进入 `cs-feat` implementation 阶段执行；禁止仅凭本协议摘要替代主入口协议。开始写代码前先打印： ```text -CS_STAGE_START feature= stage=impl skill=cs-feat-impl +CS_STAGE_START feature= stage=implementation skill=cs-feat ``` -如果不能加载 `$cs-feat-impl`，必须停下说明原因，不得降级为普通实现。 +如果不能加载 `cs-feat` 主入口，必须停下说明原因，不得降级为普通实现。 -按 `cs-feat-impl` 执行： +按 `cs-feat` implementation 阶段执行： - 先做基线预检。 - 按 checklist steps 顺序实现。 @@ -59,7 +59,7 @@ CS_STAGE_START feature= stage=impl skill=cs-feat-impl ## 4. QA 阶段 -按 `cs-feat-qa` 执行： +按 `cs-feat` QA 阶段 执行： - 读取 design、checklist、review、evidence pack、gate results、git diff。 - 只读运行验证，不直接修代码。 @@ -72,7 +72,7 @@ CS_STAGE_START feature= stage=impl skill=cs-feat-impl ## 5. Acceptance 阶段 -按 `cs-feat-accept` 执行： +按 `cs-feat` acceptance 阶段 执行： - 确认 review passed 且无 unresolved blocking。 - 确认 QA passed 且无 unresolved failed / blocked。 diff --git a/plugins/codestable/skills/cs-roadmap-impl-goal/references/protocol-gates.md b/plugins/codestable/skills/cs-epic/references/goal/support/protocol-gates.md similarity index 97% rename from plugins/codestable/skills/cs-roadmap-impl-goal/references/protocol-gates.md rename to plugins/codestable/skills/cs-epic/references/goal/support/protocol-gates.md index 18025b9..3f9e41b 100644 --- a/plugins/codestable/skills/cs-roadmap-impl-goal/references/protocol-gates.md +++ b/plugins/codestable/skills/cs-epic/references/goal/support/protocol-gates.md @@ -49,7 +49,7 @@ - checklist `dod.commands` 的 core 命令有执行证据。 - evidence pack 已生成并包含 Scope、DoD Results、Validation Commands、Scope And Cleanliness、Residual Risks。 -失败返回 `cs-feat-impl`；缺 evidence 时补证据，不能进入 review。 +失败返回 `cs-feat` implementation 阶段；缺 evidence 时补证据，不能进入 review。 ## 4. review.before_pass diff --git a/plugins/codestable/skills/cs-roadmap-impl-goal/references/protocol.md b/plugins/codestable/skills/cs-epic/references/goal/support/protocol.md similarity index 100% rename from plugins/codestable/skills/cs-roadmap-impl-goal/references/protocol.md rename to plugins/codestable/skills/cs-epic/references/goal/support/protocol.md diff --git a/plugins/codestable/skills/cs-epic/references/planning/protocol.md b/plugins/codestable/skills/cs-epic/references/planning/protocol.md new file mode 100644 index 0000000..e252378 --- /dev/null +++ b/plugins/codestable/skills/cs-epic/references/planning/protocol.md @@ -0,0 +1,268 @@ +# Epic Planning Protocol + +`.codestable/roadmap/` 是项目的"规划层"——每个子目录承载一块大需求，主文档由三块构成： + +1. **概设**：这块大需求要怎么搭、拆成哪几个模块 / 组件、各自职责 +2. **架构层详设**：模块之间的接口契约、共享数据结构、跨 feature 的协议 +3. **子 feature 拆解**：把方案分解成一串带依赖关系的子 feature 种子，feature 流程一次消费一条 + +三块**一起**作为这块大需求所有子 feature 的共同约束——每条子 feature 进 `cs-feat` design 阶段时，roadmap 第 2 块的接口契约就是它的**硬约束输入**（不能违反；要改先回 `cs-epic` planning/update）。 + +当 roadmap 涉及跨模块 module interface、seam、adapter 或依赖替身策略时，按 `support/codebase-design.md` 做内嵌 deep-module 检查；这不是切换到独立 `codebase-design` skill。 + +**为什么 roadmap 不直接写 ADR**：ADR（`requirements/adrs/`）记的是"已经拍板的稳定结构性决策"，roadmap 记的是"还没落地、可能还会变"的前瞻性接口契约。等子 feature 真正落地、对应接口稳定后，由 `cs-feat` acceptance 阶段盘点出来的领域影响触发 `cs-domain` 写 ADR——roadmap 完成过渡使命后归档。 + +**为什么单独一层**：requirements 记"要什么 + 怎么定义术语 + 拍板了哪些决策"（愿景 + 领域），roadmap 记"怎么分步实现"（执行）。把执行规划塞进 requirements 会把"要什么"和"打算怎么实现"混起来。 + +**为什么文件夹不是单文件**：拆解过程会产生草稿 / 调研 / 方案对比 / 白板转述，塞一份 md 会乱又舍不得删。每个 roadmap 一个子目录，主文档对外口径，旁边 `drafts/` 随便堆。 + +**规划原则**：roadmap 不是"任务列表"，而是一次可执行路线设计。动笔前要先把目标、约束、风险、依赖、可验证完成信号想清楚；拆出来的每条子 feature 都要能独立验证；整份 roadmap 交给用户前必须先做一次自我批判，修掉含糊验收、错误依赖和被打包过大的条目。 + +**推进原则**：一个长期软件任务能不能稳步推进，取决于有没有把"当前状态 → 下一步 → 验证 → 修复 → 记录"闭环设计清楚。roadmap 阶段要提前识别基线是否可能已坏、哪些条目承担 safety net / polish / harden、哪些产物必须落盘、哪些经验要回写到 CodeStable 知识层。没有这些，后续 feature 只是顺序执行，不是可恢复、可审计的推进。 + +> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。主文档和 items 完整模板看同目录 `reference.md`。 + +--- + +## 适用场景 + +- 用户描述"一眼看出做不完"的大需求（"加权限系统"、"做通知中心"、"接 SSO"） +- `cs-brainstorm` 判为 case 3 移交过来（brainstorm 只做分诊，不做拆解） +- 已有 roadmap 加新子 feature / 改依赖 / 调顺序 / 标废弃 +- feature-design 发现要做的事实际是多个 feature 集合，先退回拆 + +不适用：单 feature 能装下 → `cs-feat`；描述能力"是什么、边界" → `cs-req`；拍板长期规约 / 架构选型 / 加术语 → `cs-domain`；操作性沉淀 → `cs-keep`。 + +--- + +## 模式分流 + +| 用户说什么 | 模式 | +|---|---| +| "拆一下 X 需求"、"开一份 X 的 roadmap"、"我想要一个 X 系统" | `new` | +| "往 {已有 roadmap} 加子 feature"、"重排顺序"、"标 drop" | `update` | + +判断不出问用户。 + +--- + +## 单目标规则 + +每次只动一份 roadmap。一次扔出"我想要 X 和 Y"先选一个，另一个下次。理由同 req / arch——一次吐多份用户 review 不过来。 + +--- + +## 目录结构 + +``` +.codestable/roadmap/{slug}/ +├── {slug}-roadmap.md 主文档：背景 / 范围 / 模块拆分（概设）/ 接口契约（架构层详设）/ 子 feature 清单 / 排期 +├── {slug}-items.yaml 机器可读清单（feature-design 读、feature-acceptance 回写） +├── {slug}-roadmap-review.md 独立规划审查报告（人审前 gate） +└── drafts/ 可选，调研 / 讨论 / 草稿 +``` + +`{slug}` 小写字母 / 数字 / 连字符，和大需求一致（`permission-system`、`notification-center`）。平铺不嵌套 epic / sub-epic。`drafts/` 按需建，AI 不强制归档。 + +--- + +## 工作流 + +### Phase 1：锁定目标 + +模式 + 目标 + 范围。new 模式先敲定一个英文 slug（参考现有 req / arch slug 习惯）。 + +### Phase 2：读取材料 + +**共同必读**：`.codestable/attention.md` + 用户素材 + `roadmap/` 其他 roadmap（防重复）+ `requirements/` 相关 req + `requirements/CONTEXT.md` + `requirements/adrs/` 相关 ADR。 + +**按情况读**： +- 相关 compound 沉淀：`grep -r "{大需求关键词}" .codestable/compound/` +- 已有相关 feature 方案 +- 项目可用验证命令 / 已知基线：从 `.codestable/attention.md`、架构 doc、历史 acceptance、README / package scripts / CI 配置里找 build / typecheck / lint / test / e2e / 浏览器验证入口。roadmap 不直接跑完整命令，但要知道后续每条 feature 靠什么验证 + +**update 额外**：当前主文档全文 + items.yaml 当前状态 + 已启动 / 完成的子 feature 的 design / acceptance。 + +### Phase 3：拆解与起草 + +按 `reference.md` "主文档结构"和"items.yaml 格式"写**完整初稿**不分批。 + +先做 **Granularity Gate**：确认本需求为什么应该进入 roadmap，而不是 single feature 或 brainstorm；结论写进主文档第 2 节，详细判据见 `reference.md`。 + +**先写深度规划底稿**（可写进主文档第 6 / 7 节，不必单独成文件）： + +- **目标完成信号**：这块大需求做到什么可观察状态才算完成，不写"能力完善"这种感受词 +- **Top 3 风险与缓解**：最可能翻车 / 最难回滚 / 最容易漏到上线后才发现的三件事，各自写清本 roadmap 怎么降低风险 +- **非显然依赖**：外部系统、数据迁移、现有模块约束、用户拍板项，哪些会卡住后续 feature +- **关键假设**：不是用户原话、但本次规划依赖它成立的判断；review 时让用户能精确反驳 +- **基线与验证入口**：后续 feature 应优先使用哪些命令 / 手工验证入口；如果当前仓库很可能缺测试或基线不稳，要在拆解里安排 safety net / characterization 条目 +- **交付物落点**：每条子 feature 完成后应该真实落在哪些代码 / 配置 / 文档 / roadmap 状态里，避免只在汇报里说完成 +- **知识回写点**：哪些约定、环境坑、跨 feature 规则如果被验证成立，应在 acceptance 收尾时沉淀到 attention / learning / decide / guide + +同时维护 **Goal Coverage Matrix**：每个 roadmap goal / completion signal 必须追踪到至少一个 item、验证入口和证据类型；没有可追踪项时先调整拆解，不把缺口留给后续 feature-design。 + +**拆解纪律**： + +0. **先做架构方案再拆 feature**——顺序：先想模块拆分（概设第 3 节）→ 模块间接口 / 数据结构 / 协议（详设第 4 节）→ 才把方案分解成子 feature（第 5 节）。**架构方案不清楚就硬拆 feature，结果是每个 feature 各自重新发明轮子、接口对不齐** +1. **接口契约要写到 feature 可拿来当硬约束的程度**——函数签名 / 数据结构 / 协议字段 / 错误码这一级，并说明 seam placement、dependency strategy 和 adapter 是否真实需要。讲不到这级回去想。无跨模块接口（如纯前端样式调整）就明确写"无跨模块接口" +2. **每条子 feature 能当独立 feature 流程跑完并独立验证**——能单独写 design / 实现 / 验收，完成后能拿出明确证据（命令、测试、截图、接口响应、文档归并）。跑不下来颗粒度不对 +3. **依赖图必须是 DAG**——A 依赖 B 写清楚，别循环 +4. **依赖关系要有具体理由**——"B 依赖 A，因为 A 提供 XX 表结构"而不是"A 先做" +5. **先列一条最小闭环**——做完后能端到端跑通最窄路径的标第一条 +6. **明确不做的边界**——用户脑子里的"权限系统"可能包括审计日志 / 数据脱敏，不打算覆盖就写进"明确不做" +7. **不替用户决定优先级**——技术依赖之外的排序让用户拍板 +8. **最后要有收口 / 硬化意识**——UI、全栈、权限、安全、迁移类大需求，如果前面条目只覆盖功能上线，要补一条收口型子 feature 或在最后一条里明确覆盖：错误态、空态、边界输入、安全、性能、回归扫尾、文档归并 +9. **条目数量由任务形态决定**——不要为了凑固定数量合并 / 拆散。能独立验证、交付一件 coherent thing 就是一条；名字里需要写"和 / 以及"通常说明塞了两条 +10. **验收词要可证伪**——每条子 feature 的描述和 notes 里不写"完善 / 优化 / 打通"这类空词，改成"输入 A 时得到 B"、"页面 X 展示 Y"、"命令 Z 通过" +11. **需要安全网时先建安全网**——brownfield 重构、迁移、核心路径改动、历史测试薄弱时，第一条或前几条应先补 characterization / baseline tests / 观测手段，再改行为 +12. **每条都要能断点续跑**——items.yaml 的 `status` / `feature` 是恢复锚点。条目 notes 里写清阻塞项、跳过原因、外部依赖，不靠对话记忆 + +### Phase 4：自查清单 + +独立 review 前自跑一遍汇报处理： + +1. 模块拆分讲清了吗？每个模块职责一句话能说出来？ +2. 接口契约写到可执行程度了吗？feature-design 看完不需要回来问就能直接照着实现？ +3. 每条子 feature 的 slug 规范？（grep `.codestable/features/` 确认不冲突） +4. 每条描述一句话讲清楚？讲不清就拆得不够或 scope 太模糊 +5. 依赖关系是 DAG？有没有自指 / A→B→A 回环 +6. 最小闭环真的最小？第一条做完能独立给用户演示点什么？ +7. "明确不做"有没有写？没写就说"没有明确不做" +8. 和已有 req / arch 有没有矛盾？有就写"和 req-X 冲突待用户决定"，不偷偷选边 +9. **update 专项**：本次新加 / 改条目都有素材依据？凭空"加一条让看起来更完整"是漂移 +10. **update 专项**：改了接口契约的话，已 in-progress / done 的子 feature 受影响吗？影响到的列"观察项"提示用户 +11. **可证伪性自查**：每条完成信号是不是 yes/no？有没有"体验更好 / 更稳定 / 支持完善"这类无法核对的词？ +12. **条目原子性自查**：有没有一条实际包含两个可独立验收的交付？名字或描述里出现"和 / 以及 / 同时"时重点复查 +13. **最弱依赖自查**：哪条失败会拖垮最多后续条目？它的前置验证和风险缓解是否足够早？ +14. **收口覆盖自查**：是否覆盖 polish / harden / regression sweep？如果没有，写清为什么本 roadmap 不需要 +15. **基线自查**：是否知道后续 feature 的验证入口？当前基线不稳 / 测试薄弱时是否安排了 safety net？ +16. **交付物自查**：每条做完后是否能从仓库事实看到产物，而不是只从汇报看到？ +17. **知识回写自查**：哪些规则或坑会影响后续 feature？是否放进观察项，等 acceptance 验证后触发对应沉淀流程？ +18. **Goal Coverage 自查**：每个 goal / completion signal 是否已映射到 item、验证入口和 evidence type？核心目标不能只靠模糊描述或后续再说。 +19. **Interface depth 自查**：跨模块接口是否 deep；是否有 pass-through module、假 seam 或单 adapter 间接层？ + +### Phase 5：候选落盘 + 独立 review gate + +先把候选稿写到标准 roadmap 目录，给 `cs-epic` review 阶段 稳定输入： + +- **new**：建 `.codestable/roadmap/{slug}/`；写主文档 `status: draft`；写 items.yaml（每条 `status: planned`、`feature: null`）；`validate-yaml.py` 校验。 +- **update**：直接更新主文档 / items.yaml 的候选内容，结构性改动文末加变更日志；重新校验 yaml。 + +然后运行 `cs-epic` review 阶段： + +- `passed`：才能把 roadmap 交给用户 review。 +- `changes-requested`：按 finding 修 roadmap/items，重新校验并重跑 `cs-epic` review 阶段。 +- `blocked`：补齐输入、等待独立 Task agent reviewer，或让用户明确降级 local-only 后重跑。 + +### Phase 6：用户 review + +主文档 + items.yaml + `{slug}-roadmap-review.md` 完整贴给用户，并附上 Phase 4 自查结论、Top 3 风险与缓解、关键假设、review findings / residual risk。改到用户明确"可以了"。如果用户修改导致 roadmap/items 发生实质变化，回到 Phase 5 重跑 review gate。 + +### Phase 7：确认落盘 + +用户确认后，new 模式把主文档 `status` 改为 `active`、`last_reviewed` 改为当天；update 模式更新 `last_reviewed` 当天。重新校验 yaml。 + +**不改 requirements / architecture**——roadmap 是规划层，那两层只描述现状。拆解过程发现 req / 架构过时，在主文档"观察项"记一句给用户，不顺手改。 + +如果用户想把整份 roadmap 自动推进到底，确认落盘后提示下一步可以走 `cs-epic` goal 阶段：它会先完成所有子 feature design + design review，再让用户二次确认，最后输出可直接运行的 goal 指令。 + +确认落盘后再提示一句："这份 roadmap 已经改变了后续工作入口和文档索引，要不要做一轮文档与记忆整理？（`cs-docs-neat`）" 用户说不用就跳过；这是收尾引导，不是 roadmap 通过条件。 + +--- + +## 和 feature 流程的衔接 + +### feature 从 roadmap 起头 + +用户说"开始做 roadmap 里的 {子 feature}"时： + +1. `cs-feat` design 阶段（或 ff / brainstorm）起 feature 目录 +2. design frontmatter 带 `roadmap: {slug}` + `roadmap_item: {子 slug}` +3. items.yaml 对应条目 `status: in-progress`、`feature: YYYY-MM-DD-{slug}` + +职责在 `cs-feat` design 阶段，不在 epic planning 阶段。 + +### feature-design 必须把 roadmap 接口契约当硬约束 + +**roadmap 主文档第 4 节"接口契约"是 feature 的硬约束输入**——不是参考，是不能违反；要改先回 `cs-epic` planning/update。这就是为什么 roadmap 要在拆 feature 前先把架构方案定下来：让多条 feature 并行 / 串行实现时对外接口对齐。 + +feature-design 发现接口契约不合理 / 漏了 / 描述不准 → **回 `cs-epic` planning/update 改了再继续**，不要在 feature 里偷偷绕开（绕开会让下一条同模块 feature 接到老契约导致二次冲突）。 + +### acceptance 自动回写 + +`cs-feat` acceptance 阶段 收尾时如果 design frontmatter 有 `roadmap` 字段就改对应 `roadmap_item` 的 `status: done`，同时同步主文档子 feature 清单勾选状态。职责在 `cs-feat` acceptance 阶段，不在 epic planning 阶段。 + +### roadmap 自身生命周期 + +- 所有 items `done` / `dropped` 后主文档 `status: completed`，目录留作历史档案 +- 长期无进展：`status: paused`，主文档加理由 + +--- + +## 硬性边界 + +1. **不写单 feature 内部实现细节**——roadmap 写到"模块边界 / 接口契约 / 共享协议"为止，单模块内部怎么实现归 feature-design。判据：**会被多个 feature 共同遵守**归 roadmap，**只在某个 feature 内部用**归 feature-design +2. **不改愿景和结构档案**——不顺手改 requirements / architecture / 代码 / 已有 feature。问题记"观察项" +3. **不替用户拍产品优先级**——技术依赖外的排序让用户决定 +4. **单目标**——一次只动一份 +5. **不发散**——用户范围外问题记观察项不扩大 +6. **接口契约要么可执行级要么明确"无跨模块接口"**——不允许"待定 / 后面再说"。含糊掉的接口在 feature-design 各条会各自补出来必然不一致 + +--- + +## 退出条件 + +- [ ] 已锁定单一模式 + 单一目标 +- [ ] 主文档 frontmatter 完整（`doc_type: roadmap` / `slug` / `status` / `created` / `last_reviewed` / `tags`） +- [ ] 主文档含：背景 / 范围与明确不做 / **模块拆分** / **接口契约** / 子 feature 清单 / 排期 / 观察项 +- [ ] 模块拆分节每个模块职责一句话讲清 +- [ ] 接口契约节写到 feature-design 可拿来当硬约束的级别（函数签名 / 数据结构 / 协议字段 / 错误码）或明确"无跨模块接口" +- [ ] 涉及跨模块 interface / seam / adapter 时，已记录 depth / locality / dependency strategy 和 adapter 结论 +- [ ] items.yaml 每条有 `slug` / `description` / `depends_on` / `status` / `feature` +- [ ] 依赖图是 DAG 无循环 +- [ ] 最小闭环条目已标 +- [ ] Top 3 风险、非显然依赖、关键假设已写入主文档或 review 摘要 +- [ ] 每条子 feature 都有可独立验证的完成信号 / 证据类型 +- [ ] 已完成 Granularity Gate 和 Goal Coverage Matrix；每个核心目标都能追踪到 item 与证据 +- [ ] 已做可证伪性 / 条目原子性 / 最弱依赖 / 收口覆盖自查并汇报 +- [ ] 已识别验证入口 / 基线风险；必要时拆出 safety net 条目 +- [ ] 每条子 feature 的交付物能被后续 acceptance 从仓库事实核验 +- [ ] 需要后续沉淀的 convention / learning / guide / attention 候选已写入观察项 +- [ ] items.yaml 通过 `validate-yaml.py` 校验 +- [ ] Phase 4 自查清单逐条跑过并汇报 +- [ ] `{slug}-roadmap-review.md` 已通过 `cs-epic` review 阶段，没有 unresolved blocking finding +- [ ] 用户 review 通过 +- [ ] 没有顺手改 req / arch / 代码 / 已有 feature + +--- + +## 和其他工作流的关系 + +| 方向 | 关系 | +|---|---| +| `cs-req` 配合 | req 记"为什么有这个能力"、roadmap 记"打算怎么分步做出来"。大需求下可能多份 req；缺 req 提示用户先 `cs-req` | +| `cs-domain` 配合 | adrs/ 记已拍板决策、roadmap 记前瞻接口契约。读 ADR 理解现状但不改它 | +| `cs-feat` 下游 | 每条子 feature 是未来一次 feature 流程的种子；起头时 design frontmatter 带 `roadmap` / `roadmap_item` | +| `cs-feat` acceptance 阶段回写方 | acceptance 自动改 items.yaml 为 `done`，本协议只定义格式不负责回写 | +| `cs-epic` goal 阶段 下游 | 用户确认 roadmap 后，可把所有子 feature design 和后续 impl / review / QA / accept 编排成可恢复的 goal | +| `cs-onboard` 创建者 | 建 `roadmap/` 空目录 | +| `cs-brainstorm` 上游 | case 3 移交本协议，带"真问题 / 大致范围 / 可能子模块"一句话汇总。本协议不重复分诊，直接拆解 | + +--- + +## 常见错误 + +- **跳过架构方案直接拆任务**——上来就列子 feature，模块边界 / 接口没想，feature-design 各自发明轮子 +- **接口契约写得含糊**——"两边商量"、"待定"、"用一个统一的事件总线"——讲不到字段 / 签名 / 协议级。feature-design 接到这种没法当硬约束 +- 制造 pass-through module 或只有一个 adapter 的假 seam——看似解耦，实际只是多一层同步成本 +- 把单 feature 内部细节写进 roadmap（某模块内部怎么分文件 / 用哪个库）——归 feature-design +- 颗粒度失衡——一条装得下三个独立功能、另一条只改个配置 +- 依赖关系靠脑补——讲不清为什么依赖 +- 替用户排优先级 +- 和已有 req / arch 冲突不停下——自己选一边掩盖真实分歧 +- 一次做多份 roadmap +- 顺手改 req / arch +- drop 条目直接删——历史丢失 +- roadmap 跑偏成给单条子 feature 写详细方案 +- update 改接口契约不评估存量影响——已 in-progress / done 的 feature 没人看到契约变了 +- 跳过 `cs-epic` review 阶段 直接让用户拍板——用户只能看到规划表面，看不到接口、依赖、验收策略的独立审查结论 diff --git a/plugins/codestable/skills/cs-roadmap/reference.md b/plugins/codestable/skills/cs-epic/references/planning/reference.md similarity index 97% rename from plugins/codestable/skills/cs-roadmap/reference.md rename to plugins/codestable/skills/cs-epic/references/planning/reference.md index 6354e57..4cc6606 100644 --- a/plugins/codestable/skills/cs-roadmap/reference.md +++ b/plugins/codestable/skills/cs-epic/references/planning/reference.md @@ -1,6 +1,6 @@ -# cs-roadmap 参考模板 +# Epic Planning Reference -SKILL.md 只保留流程骨架，具体格式在这里。 +本文件提供 epic planning 的输出格式、items schema 和 review checklist 模板。 --- @@ -204,7 +204,7 @@ items: ``` planned → in-progress （feature-design 启动时由 design 改） in-progress → done （feature-acceptance 完成时由 acceptance 改） -planned → dropped （用户决定不做，roadmap update 改） +planned → dropped （用户决定不做，由 `cs-epic` planning/update 改） done / dropped 终态 ``` @@ -261,4 +261,4 @@ python .codestable/tools/validate-yaml.py --file .codestable/roadmap/{slug}/{slu > > 有修改意见直接说，确认后把 roadmap 从 `draft` 标为 `active`。 -> 人工 review 前必须先有 `{slug}-roadmap-review.md` 且 `status: passed`。用户修改 roadmap/items 后，实质变化要重跑 `cs-roadmap-review`。 +> 人工 review 前必须先有 `{slug}-roadmap-review.md` 且 `status: passed`。用户修改 roadmap/items 后，实质变化要重跑 `cs-epic` review 阶段。 diff --git a/plugins/codestable/skills/cs-roadmap/references/codebase-design.md b/plugins/codestable/skills/cs-epic/references/planning/support/codebase-design.md similarity index 93% rename from plugins/codestable/skills/cs-roadmap/references/codebase-design.md rename to plugins/codestable/skills/cs-epic/references/planning/support/codebase-design.md index 7a72974..958da0e 100644 --- a/plugins/codestable/skills/cs-roadmap/references/codebase-design.md +++ b/plugins/codestable/skills/cs-epic/references/planning/support/codebase-design.md @@ -1,6 +1,6 @@ # Roadmap 内嵌 Codebase Design 检查 -这份 reference 是 `cs-roadmap` 的内嵌架构规划检查，不是独立 skill 入口。它只用于补强 roadmap 第 3 节模块拆分和第 4 节接口契约。 +本文件是 `cs-epic` planning 阶段的内嵌架构规划检查清单，只用于补强 roadmap 第 3 节模块拆分和第 4 节接口契约。 ## 什么时候用 diff --git a/plugins/codestable/skills/cs-epic/references/review/protocol.md b/plugins/codestable/skills/cs-epic/references/review/protocol.md new file mode 100644 index 0000000..fb4b83d --- /dev/null +++ b/plugins/codestable/skills/cs-epic/references/review/protocol.md @@ -0,0 +1,274 @@ +# Epic Review Protocol + +本阶段是 roadmap 交给用户人工确认前的规划审查 gate。它只读 roadmap、items、相关文档和必要代码事实，只写 `{slug}-roadmap-review.md`，不直接改 roadmap、不替用户批准 roadmap、不推进 feature design。 + +目标不是追求"规划看起来完整"，而是确认这份 roadmap 已经具备让用户有效 review 的条件：目标可证伪、范围边界清楚、模块拆分与接口契约可执行、子 feature 可独立验证、依赖 DAG 合理、风险和验证策略提前暴露。 + +> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。roadmap 的具体结构以目标 `{slug}-roadmap.md` / `{slug}-items.yaml` 和项目内共享口径为准。 +> 报告语言：roadmap-review 报告正文必须按 `.codestable/attention.md` 用**中文**；若草稿用了英文，落盘前先改写为中文。frontmatter / yaml 字段不翻译。 + +--- + +## 输入 + +进入 review 前必须读取： + +- `.codestable/attention.md` +- `.codestable/roadmap/{slug}/{slug}-roadmap.md` +- `.codestable/roadmap/{slug}/{slug}-items.yaml` +- roadmap 目录下相关 `drafts/` 材料（只读与本次候选直接相关的） +- roadmap frontmatter 指向的 requirement / architecture 文档 +- roadmap 第 7 节观察项提到的相关文档 +- 相关 compound 沉淀：用项目搜索工具按大需求关键词检索 decision / learning / explore / trick +- items.yaml 中已存在 `feature` 字段的 feature design / acceptance（update 模式或复审时） +- roadmap 中接口契约或模块拆分引用到的关键代码位置 +- 独立 Task agent reviewer 输出（如果本轮已启动） + +没有代码引用时不强行扫全仓库；但 roadmap 声称复用现有模块、接口、命令、配置或数据结构时，必须读对应代码或文档事实核验。 + +--- + +## 启动检查 + +1. roadmap 主文档存在，frontmatter `doc_type=roadmap`，`slug` 与目录一致，`status` 是 `draft|active|paused|completed` 之一。 +2. items.yaml 存在，`roadmap` 与 slug 一致，`items` 非空。 +3. items.yaml 每条有 `slug` / `description` / `depends_on` / `status` / `feature` / `minimal_loop`。 +4. 依赖图能解析；有循环、自指、未知依赖时直接列 blocking。 +5. 如果已有 `{slug}-roadmap-review.md`： + - `status: passed` 且 roadmap/items 未变化：提示可进入用户 review。 + - `status: changes-requested` / `blocked`：读取旧 findings，确认是否复审。 + - roadmap/items 已变化：重新 review，并在报告里记录轮次。 + +--- + +## 独立 Task agent reviewer gate + +本阶段必须优先启动独立 Task agent reviewer；当前 agent 的本地审查只能作为合并与事实核验，不能替代独立审查。只有运行时确实没有 Task agent 能力、provider 不可用且无法配置，或用户在看到降级风险后明确授权，才允许 `local-only` / `skipped-by-user`。批量 roadmap、赶时间、主 agent 自认为风险低，都不是降级理由；需要授权降级时，先按 `.codestable/reference/approval-conventions.md` 写 `approval-report.md`，再让用户选择。 + +一旦本轮应该启动或已经启动独立 Task agent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 reviewer 返回前定稿 `{slug}-roadmap-review.md`、不能给出 `passed`、不能把 roadmap 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。 + +**检测由主 agent 在运行时自检自己的工具**，不靠脚本猜环境——主 agent 最清楚自己手上有哪些工具。按 Task agent 选择规则启动独立 Task agent reviewer（优先 Paseo subagent，否则当前宿主原生 Codex/Claude Task/Agent）： + +1. **有 `mcp__paseo__create_agent` 工具**：必须优先用 Paseo subagent 做只读独立审查（首选：能换 provider，做到真正异构审查）。启动前先加载 / 读取 `paseo` skill 的当前说明，并遵守它的规则：读取 `~/.paseo/orchestration-preferences.json`，使用 `providers.audit`，不要硬编码 Claude 或 Codex。不要无限轮询运行中的 agent；如果 reviewer 已启动但结果未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。 +2. **否则有当前宿主原生 Codex/Claude Task/Agent 工具**：用原生 Task agent 做独立上下文审查。如属同类 agent，在报告里记录降级和残余风险。 +3. **两者都没有**：本地 review 只能在记录 `local-only` 且获得必要授权后定稿；没有授权时报告 `blocked`，不要伪装启动。 + +独立 Task agent reviewer prompt 必须只给原始材料和边界，不透露本地 review 结论： + +```text +你是 CodeStable roadmap 的独立规划审查 agent。只读，不修改文件，不更新 roadmap/items。 + +请读取： +- .codestable/attention.md +- {roadmap_path} +- {items_path} +- roadmap frontmatter 指向的 requirement / architecture 文档 +- roadmap 相关 compound / draft 材料 +- roadmap 引用到的关键代码或命令入口 + +按 epic review 的严重度语义输出：blocking / important / nit / suggestion / learning / praise / residual-risk。 +重点审查：目标完成信号、范围与明确不做、模块拆分、interface depth / seam placement / adapter、接口契约可执行性、子 feature 原子性、依赖 DAG、最小闭环、验证策略、风险缓解、知识回写点、用户是否能据此有效拍板。 +每条 finding 必须有 roadmap/items/doc/code 事实证据、影响、建议修复边界。 +不要写 {slug}-roadmap-review.md；只把审查结果回传给主 agent。 +``` + +主 agent 仍是最终审查责任方：必须逐条核验独立 Task agent reviewer 的 finding，去重、定级、合并进 `{slug}-roadmap-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。 + +--- + +## 审查流程 + +### 1. 范围与事实 + +- 用 roadmap 第 1/2 节确认目标、覆盖范围、明确不做、关键假设。 +- 用第 3/4 节确认模块拆分和接口契约是否足够支撑多个 feature 共用。 +- 用第 5 节和 items.yaml 对齐所有子 feature：slug、描述、所属模块、依赖、状态、feature 绑定、minimal_loop。 +- 用相关 req / arch / compound 判断有没有冲突、重复规划或遗漏约束。 +- 用代码事实核验 roadmap 对现有模块、命令、接口、配置、数据结构的描述。 + +### 2. 独立审查合并 + +- 记录主 agent 自检结果：`paseo` / `native-agent` / `local-only`。 +- 没有启动独立 Task agent reviewer 时，记录确无能力 / provider 不可用 / 用户授权降级；未满足这些条件时不得定稿 `passed`。 +- 启动 Paseo subagent / 原生 Task agent 后，最终 verdict 必须等 reviewer 返回。 +- reviewer 返回后逐条做本地事实核验；能用文档 / 代码 / items 证据支撑才合并。 +- reviewer 失败、权限阻塞、超时或仍在运行时，不要默默降级；报告 `status: blocked`。 + +### 3. 规划审查 + +至少覆盖： + +- 目标完成信号：是否能观察、能验收、能判定完成 / 未完成。 +- 范围与明确不做：是否具体，能否防止后续 feature 偷偷扩范围。 +- 模块拆分：职责是否清楚，是否有重复模块、万能模块、遗漏模块。 +- Module/interface 设计：是否制造 pass-through module；跨模块 interface 是否 deep；seam / adapter 是否真实需要；dependency strategy 是否支撑后续测试。 +- 接口契约：是否写到函数签名 / 数据结构 / 协议字段 / 错误码级别；无跨模块接口时是否明确写明。 +- 子 feature 原子性：每条能否独立 design / implement / review / QA / accept；描述是否可证伪。 +- 依赖 DAG：是否无环，依赖理由是否具体，最弱依赖是否先验证。 +- 最小闭环：第一条或最小路径做完后是否能端到端演示。 +- 验证与基线：是否识别 build / typecheck / lint / test / e2e / 手工验证入口；基线不稳时是否安排 safety net。 +- 风险与恢复：Top 风险、外部依赖、迁移 / 权限 / 安全 / 回滚是否提前暴露。 +- 交付物与知识回写：后续 acceptance 是否能从仓库事实核验产物；稳定约定 / 坑点是否有沉淀候选。 + +### 4. Roadmap Review Invariants 与证据分级 + +每轮 review 必须形成 Evidence Confidence Ledger。证据分级只描述依据来源，不计算质量分： + +- `E` Embedded：roadmap / items.yaml / checklist / 命令输出里直接可见。 +- `C` Context：相关 req / arch / compound / 代码事实支撑。 +- `H` Heuristic：工程经验或 reviewer 判断，缺少直接仓库证据。 + +核心 invariants： + +- Granularity Gate 能解释为什么进入 roadmap，而不是 single feature / brainstorm。 +- Goal Coverage Matrix 中每个核心完成信号都有 item、验证入口和 evidence type。 +- items.yaml 仍是 DAG，且最小闭环可独立验收。 +- 接口契约可被 feature-design 当硬约束。 +- 跨模块 interface 有 depth / seam / dependency strategy 依据；无跨模块接口时明确 not-applicable。 +- 核心检查若只有 `H` 证据，不能静默 `passed`；至少写入 residual risk，必要时列 important / blocking finding。 + +--- + +## 严重度 + +- `blocking`：必须先修。会导致用户无法有效 review、feature 不能独立执行、接口契约不可用、依赖循环、明显违反 req / arch、关键风险未覆盖、验收不可证伪。 +- `important`：应该修；若用户决定延后，必须在 roadmap review 和用户 review 摘要中明确记录。 +- `nit`：小的清晰度或一致性建议，不阻塞。 +- `suggestion`：替代拆法或补强思路，不要求本次采用。 +- `learning`：知识性说明，不要求动作。 +- `praise`：记录值得保留的规划做法；少量即可。 +- `residual-risk`：review 无法完全消除的不确定性，需要用户 review 或后续 feature-design 重点复核。 + +不要把个人偏好的拆法升级成 blocking。blocking 必须能用 roadmap 契约、items 事实、相关文档、代码事实或可靠工程原则支撑。 + +--- + +## 报告模板 + +报告路径：`.codestable/roadmap/{slug}/{slug}-roadmap-review.md`。 + +```markdown +--- +doc_type: roadmap-review +roadmap: {slug} +status: passed|changes-requested|blocked +reviewed: YYYY-MM-DD +round: 1 +--- + +# {slug} roadmap 审查报告 + +## 1. Scope And Inputs + +- Roadmap: {path} +- Items: {path} +- Related docs: {requirements / architecture / compound / drafts} +- Code facts checked: {paths / none} + +### Independent Review + +- Status: not-available|skipped-by-user|local-only|pending|completed|failed|blocked +- Detection: paseo|native-agent|local-only|skipped +- Provider / agent: {providers.audit / agent id / none} +- Raw output: {摘要 / 路径 / none} +- Merge policy: {已逐条核验 / 未启用原因 / pending 时不得定稿} +- Gate effect: {none | blocks final verdict until completed / user-approved downgrade} + +## 2. Roadmap Summary + +- Goal completion signal: {摘要} +- Module split: {摘要} +- Interface contracts: {摘要} +- Items: {数量 + minimal loop + 风险热点} +- Dependency shape: {DAG / 问题} + +## 3. Findings + +### blocking + +- [ ] RMR-001 `{path#section|items.slug|file:line}` {问题} + - Evidence: {事实} + - Impact: {为什么阻塞用户 review / 后续 feature} + - Expected fix scope: {修复边界} + +### important + +- [ ] RMR-00N `{证据位置}` {问题} + - Evidence: {事实} + - Impact: {影响} + +### nit + +- [ ] RMR-00N `{证据位置}` {建议} + +### suggestion + +- [ ] RMR-00N {建议} + +### learning + +- {可复用规划经验或注意点} + +### praise + +- {值得保留的做法} + +## 4. User Review Focus + +- 用户需要重点拍板：{决策 / 假设 / 优先级} +- 后续 feature-design 需要重点复核：{接口 / 风险 / 验证} +- 不能靠 roadmap review 完全确认的点：{列表} + +## 5. Evidence Confidence Ledger + +| Check | Verdict | Evidence Class | Basis | Follow-up | +|---|---|---|---|---| +| Granularity Gate | pass|warn|fail | E|C|H | {路径 / 事实 / 判断依据} | {none / 复核点} | +| Goal Coverage Matrix | pass|warn|fail | E|C|H | {依据} | {复核点} | +| DAG and minimal loop | pass|warn|fail | E|C|H | {依据} | {复核点} | +| Interface contract usability | pass|warn|fail | E|C|H | {依据} | {复核点} | +| Module interface depth | pass|warn|fail|n/a | E|C|H | {依据} | {复核点} | + +Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。 + +## 6. Residual Risk + +- {风险 + 用户 review / feature-design 如何处理；没有写 none} + +## 7. Verdict + +- Status: passed|changes-requested|blocked +- Next: 交给用户 review | 回 `cs-epic` planning 阶段 修订后重跑 `cs-epic` review 阶段 | 等独立 Task agent reviewer 完成 / 用户确认降级后重跑 +``` + +没有某类 finding 时写 `none`，不要删除章节；下一轮复审要能对比。 + +--- + +## 退出条件 + +- [ ] 已读取 attention、roadmap、items、相关 req / arch / compound / drafts。 +- [ ] 已按 roadmap 声明核验必要代码或命令事实。 +- [ ] 已确认 items.yaml 可解析，依赖图无未知节点；有问题已列 finding。 +- [ ] 已按 Task agent 选择规则启动独立 reviewer；若未启动，已记录确无能力 / provider 不可用 / 用户授权降级。 +- [ ] 如果启动了独立 Task agent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。 +- [ ] 已审查目标、范围、模块、接口、feature 原子性、依赖、最小闭环、验证、风险、知识回写。 +- [ ] 已检查 Granularity Gate、Goal Coverage Matrix 和 Roadmap Review Invariants。 +- [ ] 已写 Evidence Confidence Ledger；核心检查 H-only 时没有静默 passed。 +- [ ] 已写 `.codestable/roadmap/{slug}/{slug}-roadmap-review.md`。 +- [ ] 有 blocking / 未处理 important 时指向 `cs-epic` planning 阶段 修订并重跑 review。 +- [ ] 无 blocking 且 important 已处理或明确接受时，明确告诉用户下一步是 roadmap 人工 review。 + +--- + +## 容易踩的坑 + +- 把 roadmap review 做成语病检查，没审接口契约和依赖图。 +- 只读主文档，不核对 items.yaml。 +- 不读 requirement / architecture，导致规划和现状冲突没发现。 +- 接口契约写着"待定"也放过，后续每条 feature 各自发明接口。 +- 子 feature 里塞多个可独立验收的交付，却只当一条。 +- 把批量 roadmap 或赶时间当成 local-only 降级理由。 +- 启动独立 Task agent reviewer 后结果还没回来，就把本地 review 定稿为 passed。 +- 外部 reviewer 的结论没经本地事实核验就照抄。 +- review 报告没有落盘，导致用户 review 和后续 design 没有可追溯输入。 diff --git a/plugins/codestable/skills/cs-feat-accept/SKILL.md b/plugins/codestable/skills/cs-feat-accept/SKILL.md index a20780e..d55756d 100644 --- a/plugins/codestable/skills/cs-feat-accept/SKILL.md +++ b/plugins/codestable/skills/cs-feat-accept/SKILL.md @@ -1,289 +1,23 @@ --- name: cs-feat-accept -description: Feature acceptance。触发：实现、review、QA 后最终验收，或准备 merge/出验收报告。 +description: Feature acceptance 兼容入口。旧调用保留；执行时转入 cs-feat 主流程的 acceptance 阶段。 --- # cs-feat-accept -## 启动必读 +本技能是 `cs-feat` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_stage: acceptance` -代码已经写完，但流程没结束。本阶段做四件事，缺一不可： +## 执行规则 -1. **核对实现有没有偏离方案**——逐层对照 `{slug}-design.md`，发现偏差当场修，**不是在报告里"记一下"**就过去 -2. **盘点领域影响**——识别本次是否引入新术语 / 结构性决策，提示用户走 `cs-domain` 写 CONTEXT.md / ADR（不在 accept 里代写） -3. **能力落档到 requirement**——draft req 对应的能力实现完成后升级为 current（保留愿景，追加变更日志）；从未写过 req 的能力 backfill -4. **完成状态回写到 roadmap**——方案 frontmatter 有 `roadmap` / `roadmap_item` 字段时**必须**改 items.yaml 对应条目为 `done` 并同步主文档 +1. 按已安装 skill 名称加载 `cs-feat` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-feat` 主协议继续执行，并带上入口意图 `requested_stage: acceptance`。 +3. 不要要求用户重新调用 `cs-feat`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -漏掉任何一件的代价：CONTEXT.md / adrs/ 没跟上下个 feature 读到错术语；req 和实际能力脱节；roadmap 规划层和实际进度脱节，下次推进会重复跑流程。 +## 维护规则 -**验收原则**：acceptance 是最终审计，不是实现汇报的整理。要重新读取原始 design 和 checklist，以最终工作区为准逐项复验；实现阶段说通过只能当线索，不能当结论。发现缺口要先修代码 / 方案 / 文档并重验，再写通过。 - -**推进原则**：验收阶段要用仓库事实关闭任务，而不是用对话自述关闭任务。最终结论必须回答四个问题：原始契约是否满足、验证证据是否足够且在最终状态仍成立、承诺交付物是否真实落盘、这次学到的可复用知识是否进入 CodeStable 的沉淀出口。 - -**独立审计边界**：可按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动只读 acceptance auditor，复核 design/checklist/review/QA/final diff 和状态回写候选；但 auditor 只能返回 findings，不得写 `{slug}-acceptance.md`、checklist、roadmap、requirement 或状态文件。acceptance 是流程关闭动作，最终 verdict、状态推进和文件写入必须由当前主流程 owner 完成。 - -**没产出报告 = 工作流未完成**。后人查"上次这个功能验收时确认了哪些行为"，没报告就只能翻 git diff 重新推断。 - -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md` 第 0 节。 -> -> 本技能默认 **L3**，遵守 Global Route Governance：不在 accept 阶段自由重写长期 requirement，capability-boundary 变化必须先有 owner-approved req delta，缺 delta 就停下写 `approval-report.md`。详见同包 `reference.md`。 - ---- - -## 跟 design 的章节强依赖 - -本技能整套对照表按 design 当前章节编号硬编码。**design 升级章节名 / 编号时本技能必须同步**，否则下面所有"第 X 节"指针都指错地方。 - -**标准 design 章节快照**： - -- 第 0 节：术语约定 -- 第 1 节：决策与约束（需求摘要 / 复杂度档位 / 关键决策 / 前置依赖） -- 第 2 节：名词与编排（2.1 名词层 / 2.2 编排层 / 2.3 挂载点 / 2.4 推进策略） -- 第 3 节：验收契约（关键场景清单 + 反向核对项） -- 第 4 节：领域影响（新术语 / 结构性决策 / 流程级约束） - -**Fastforward design**：第 0 需求摘要 / 第 1 设计方案 / 第 2 验收标准 / 第 3 推进步骤 - ---- - -## 启动检查 - -1. **代码确实实现到位**——git status / 最近提交看到本功能改动，否则退回 implement -2. **方案 doc 完整**——frontmatter `doc_type=feature-design` / `feature` 一致 / `status=approved` / `summary` 非空 / `tags` ≥ 2；标准 design 第 0/1/2/3 节 + 第 4 节已填写 -3. **`{slug}-checklist.yaml`**——存在且 `feature` 一致；`steps` 全 `done`（有 `pending` 退回 implement）；`checks` 非空全 `pending` -4. **`{slug}-review.md`**——存在且 frontmatter `doc_type=feature-review`、`status=passed`；没有 unresolved `blocking` findings。缺失 → 先跑 `cs-code-review`；有 blocking → 退回 `cs-feat-impl` review-fix；status 不是 passed → 不进入验收 -5. **Gate / DoD evidence**——goal / gate 模式下读取 `{slug}-evidence-pack.md`、`{slug}-gate-results.json`、`{slug}-dod-results.json`；缺失或 blocking DoD 无 pass evidence 时退回 implementation gate。 -6. **验证证据来源**——独立 `cs-feat-qa` 不是 standalone accept 的硬前置；但验收必须有同等强度的验证证据： - - 已有 `{slug}-qa.md`：读取并复核。frontmatter 必须 `doc_type=feature-qa`、`status=passed`；failed / blocked → 退回 `cs-feat-impl` qa-fix；status 不是 passed → 不进入验收。 - - 没有 `{slug}-qa.md`：不要强制切去跑 `cs-feat-qa`。在本次 accept 里建立 `Inline Verification Matrix`，对照 design 第 3 节、checklist checks、review Test And QA Focus / residual risk 和项目测试入口，现场运行验证，并把证据写入 acceptance 第 3 节和第 10 节最终审计。这个模式等价于“accept-inline QA”，但不额外生成 QA 报告。 - - Goal 模式例外：`cs-roadmap-impl-goal` 协议明确要求逐 feature 生成 QA 报告；在 goal 模式缺 `{slug}-qa.md` 时按 goal protocol 停止，不走 accept-inline。 -7. **核心证据复核**——不管证据来自 QA 报告还是 accept-inline，都按同一标准复核： - - 功能性或 mixed feature：design 第 3 节、checklist checks、review QA focus 中的核心功能路径必须有运行证据。若核心路径未运行、真实用户/API/运行时路径未验证、必跑命令未执行，acceptance 必须写 `status=blocked`。下一步按原因选择：代码/测试缺口 → `cs-feat-impl` qa-fix 后重跑 review 和 accept-inline；环境缺口 → 先补环境；用户希望独立 QA 报告 → 跑 `cs-feat-qa`。 - - 非功能性 feature：不要求 e2e / browser / API，但必须写明为什么不需要端到端运行，并提供静态检查、diff 复核、文档一致性、schema/快照/类型/构建/目标测试等替代证据。缺说明或证据不足时继续补证据，不直接通过。 -8. **上下文读全**——方案 doc 全文（重点：第 1 节明确不做、2.1 接口示例、2.2 流程级约束、2.3 挂载点、第 3 节场景）+ checklist + review 报告（findings / residual risk / Test And QA Focus）+ QA 报告（如有：Feature type / Core evidence gate / Verification Matrix / Command Results / Scenario Results / residual-risk）+ evidence pack / DoD results / Gate results + accept-inline 验证矩阵（如无 QA 报告）+ implement 完成汇报里的基线预检 / step 证据 / 实际交付物索引 / 知识回写候选 + 第 4 节提到的领域影响候选 + `requirements/CONTEXT.md` + 相关 ADR + 本次代码改动（git log / diff） -9. **断点恢复**——`{slug}-acceptance.md` 已存在且部分填好 → 从下一个未完成节继续，跳过 checks 中已 `passed` 的项；汇报"上次做到第 X 节，从第 Y 节继续" - -**Fastforward design 验收报告映射表**： - -| 验收报告节 | 标准 design 对照 | Fastforward design 对照 | -|---|---|---| -| 1 接口契约核对 | 第 2.1 接口示例 | 第 1 节改动点 | -| 2 行为与决策核对（含挂载点） | 第 1 节 + 第 2.2 + 第 2.3 | 第 0 节；挂载点现场盘点 | -| 3 验收场景核对 | 第 3 节场景清单 + 反向核对 | 第 2 节验收标准 | -| 4 术语一致性 | 第 0 节 + 第 2.1 命名 | 检查代码命名一致性 | -| 5 领域影响盘点 | 第 4 节 | 通常无；写"无领域维度变更" | - ---- - -## 验收报告模板 - -逐节填写**别跳节**。报告路径在 feature 目录下（位置看 `shared-conventions.md` 第 0 节）。 - -```markdown ---- -doc_type: feature-acceptance -feature: YYYY-MM-DD-slug -status: passed|blocked -accepted: YYYY-MM-DD -round: 1 ---- - -# {功能名称} 验收报告 - -> 阶段：阶段 3（验收闭环） -> 验收日期：YYYY-MM-DD -> 关联方案 doc：{方案 doc 路径} - -## 1. 接口契约核对 - -对照方案第 2.1 节名词层逐一核查： - -**接口示例逐项核对**： -- [ ] 示例 A（{文件路径 + 函数名}）：示例输入→输出 → 代码实际行为：{一致 / 偏差说明} - -**名词层"现状 → 变化"逐项核对**： -- [ ] 名词 X：声称的变化 → 代码改动：{一致 / 偏差} - -**流程图核对**（第 2.2 节开头 mermaid 图）： -- [ ] 图中节点 / 调用关系在代码均有实际落点（grep 确认） - -发现偏差**先修代码或回填方案 doc**。报告里写"已知偏差暂不处理"是反模式——下次按方案找代码会被绊倒。 - -## 2. 行为与决策核对 - -对照方案第 1 节 + 第 2.2 节： - -**需求摘要逐项验证**： -- [ ] 行为 A：{描述 + 实测结果} - -**明确不做逐项核对**（用第 3 节"反向核对项"）： -- [ ] 范围外事项 X **确实没做**（grep / review 确认） - -**关键决策落地**： -- [ ] 决策 D1：{决策内容} → 代码体现：{描述} - -**编排层"现状 → 变化"逐项核对**： -- [ ] 变化 V1：{在哪一步插入 / 哪条分支变更} → 代码实际落点 - -**流程级约束核对**（错误语义 / 幂等 / 并发 / 扩展点 / 可观测点）： -- [ ] 纪律 R1：{描述} → 代码遵守方式 - -**挂载点反向核对（可卸载性）**——对照第 2.3 节，必做两件事： -- [ ] 挂载点 M1：清单条目 → 代码实际落点：{一致 / 偏差} -- [ ] **反向核查**（grep）：本 feature 在代码里的所有引用是否都落在清单内？清单外的引用 → 漏记，补进第 2.3 节 -- [ ] **拔除沙盘推演**：按清单逆向操作后是否还有残留？残留 → 写进"遗留"或补挂载点 - -Fastforward 方案没有挂载点清单 → 现场 grep 盘点本次改动命中的挂入位置作为卸载依据。 - -## 3. 验收场景核对 - -对照方案第 3 节关键场景清单，逐条可观察证据验证： - -- [ ] **S1**：{场景"输入 / 触发 → 期望可观察结果"} - - 证据来源：{类型系统 / 单测 / 集成 / 手工 / 肉眼} - - 结果：{通过 / 未通过 + 原因 + 补救} - -**功能性前端改动必须浏览器肉眼验证**（typecheck 通过不代表用户用起来对；非功能性前端改动用替代证据复核）： -- [ ] UI 区域 X：浏览器验证 OK / 截图链接 - -**review 报告重点复核**： -- [ ] `{slug}-review.md` 第 4 节 Test And QA Focus 已逐条覆盖 -- [ ] `{slug}-review.md` 第 5 节 residual risk 已逐条处理 / 明确留作用户确认遗留 - -**QA 报告重点复核**： -- [ ] 验证证据来源：`{slug}-qa.md` / accept-inline verification -- [ ] QA 报告或 Inline Verification Matrix 已覆盖 design 关键场景和 review QA focus -- [ ] QA 报告或 Inline Verification Matrix 中的 feature 性质与核心证据说明合理：功能性核心路径有运行证据；非功能性 feature 有替代证据理由 -- [ ] failed / blocked 项为 none -- [ ] residual-risk 已逐条处理 / 明确留作用户确认遗留，且没有承载核心验收缺口 -- [ ] Evidence pack、DoD Results、Gate Results 已复核；blocking DoD 均有 pass evidence - -## 4. 术语一致性 - -对照方案第 0 节 + 第 2.1 节命名 grep 代码： - -- 术语 X：代码命中 N 处全部一致 ✓ -- 防冲突：禁用词 grep 无命中 ✓ - -发现不一致 → 改代码，别在报告里写"已知差异"。 - -## 5. 领域影响盘点（提示而非代写） - -**目标**：识别本次 feature 是否引入了应进 CONTEXT.md / adrs/ 的内容，**提示用户走 cs-domain**——不在 accept 里替它写。 - -对照方案第 4 节 + 实际实现，三类信号逐项盘点： - -- **新名词** → `requirements/CONTEXT.md` 候选：新增 / 改名的实体、类型、对外契约；grep CONTEXT.md 看是否已有定义，没有就提示"走 cs-domain 加术语？" -- **结构性选择**（满足 ADR 3 判据：难回退 + 不显然 + 真权衡）→ `requirements/adrs/` 候选：新增模块 / 跨模块接口模式 / 新依赖选型 / 拒绝的备选 -- **流程级约束** → `requirements/adrs/` 候选：稳定的错误语义 / 幂等约束 / 扩展点规约 - -逐项核对： -- [ ] 候选 X（{术语 / 结构选择 / 流程约束}）：建议 {cs-domain 写 CONTEXT / 写 ADR} → 已建议用户 ✓ / 不需要（理由：{具体}） - -**不在 accept 里直接改 CONTEXT.md 或写 ADR**——这是 cs-domain 的事。accept 只盘点 + 建议。本节是登记表，不是动作。 - -## 6. requirement delta / clarification 回写 - -req 是能力愿景层，但 **accept 阶段不自由重写长期 requirement**（Global Route Governance，本技能 L3）。对照方案 frontmatter 的 `requirement`、第 1 节需求摘要、feature 目录下已有 `*-req-delta.md` 与 clarifications： - -- 纯重构 / 无 requirement 影响 → 写"无 requirement 影响"，跳过。 -- 新增了用户可感能力，或改了边界 / 用户故事 / pitch：**必须有 owner-approved req delta** 才机械应用（`draft`→`current` 或刷新 current，保留原始愿景 + 变更日志）；**没有 approved delta 就停下**写 `approval-report.md`，回 clarification / `cs-req` delta 流程，不在 accept 里直接落 current。 -- `requirement` 指向 current 但本次未改用户视角 → 写"req-{slug} 未变"。 - -完整 7 分支判据与 Global Route Governance 全文见同包 `reference.md`（按 `SKILL.md` 所在目录解析）。这是受 delta 约束的实际写文件动作，不是把 accept 当成自由重写 requirements 的机会。 - -## 7. roadmap 回写 - -对照方案 frontmatter 的 `roadmap` / `roadmap_item`： - -- [ ] 两字段都空（feature 未从 roadmap 起头）→ 跳过，写"非 roadmap 起头" -- [ ] 两字段都有值： - - 打开 `.codestable/roadmap/{roadmap}/{roadmap}-items.yaml` - - 找到 `slug: {roadmap_item}`，核对当前 `status: in-progress` + `feature: {目录名}`——不对停下来找原因 - - 改 `status: done`，用 `validate-yaml.py` 校验 - - 同步 `{roadmap}-roadmap.md` 主文档第 3 节子 feature 清单的对应条目状态 -- [ ] 两字段不一致（只填了一个）→ 停下来补齐或澄清 - -衔接协议看 `shared-conventions.md` 第 2.5 节。和 req 同规则：实际写文件的动作。 - -## 8. attention.md 候选盘点 - -回看本次实现，结合 implement 完成汇报里的"知识回写候选"，盘点"每个 feature 都会撞一次"的环境 / 工具 / 工作流类信息。典型候选：编译命令、代理配置、本地起服务步骤、反复踩的环境坑、仓库内非显然的工作流约定。 - -**判据**：下一个 feature 的 AI 还会再踩一次的事才记。一次性踩坑、和具体业务耦合的细节归 learning / decide。 - -- [ ] 无候选：写"本 feature 未暴露需要补入 attention.md 的内容" -- [ ] 有候选：列出来，**不擅自写入**——本节只登记，落不落由用户在"退出后"环节定 - - 候选 1：{描述 + 建议放 attention.md} - -同时分流其他知识出口： - -- 稳定技术约束 / 目录归属 / 命名规约 / 可复用坑点 / 库 API 经验 / 调试路径 → 第 9 节遗留或退出后提示 `cs-keep` -- 用户操作指南或开发者指南变化 → 退出后提示 `cs-doc-tutorial` -- 公开 API / 组件 / 命令表面变化 → 退出后提示 `cs-doc-api` - -## 9. 遗留 - -- 后续优化点（已开 issue 或加入 issue 列表）：{列表} -- 已知限制：{列表} -- 实现阶段"顺手发现"列表：{列表} -``` - ---- - -## 核对节奏 - -逐节做。每节完成后**逐条更新 `{slug}-checklist.yaml` 的 `checks`**：通过 → `passed`，失败 → `failed`（先修代码 / 方案再改回 `passed`）。所有 checks 全 `passed` 后报告才算完成。 - -第 1/2 节最容易暴露偏离，先做。第 2 节挂载点反向核对**必须实际 grep + 沙盘推演**，不能凭印象勾选。第 5/6/7 节是写文件的动作，不是自评。 - -## 最终审计节奏 - -9 节报告填完、checks 全部 `passed` 之后**还不能直接宣布完成**，再跑一轮 final audit 用最终工作区反查原始设计：重读原始契约、聚合命令复验、场景抽样复核、交付物 / 完整工作区 / diff 清洁度 / 知识沉淀复核、覆盖率诚实标记（写 `re-verified` / `trust-prior-verify` 数）。发现缺口先把对应 check 改回 `failed`、只修失败项、重跑对应节与 final audit；同一缺口三轮仍失败则停下交还用户，不写"通过"。 - -**完整 8 步、缺口处理与「## 10. 最终审计」报告模板见同包 `reference.md`**（按 `SKILL.md` 所在目录解析）。验收报告在第 9 节后追加第 10 节最终审计。 - ---- - -## 退出条件 - -- [ ] 验收报告 9 节都填完 -- [ ] review 报告存在且 `status=passed`，无 unresolved blocking findings -- [ ] 验证证据来源已明确：QA 报告 passed，或 acceptance 第 3 / 10 节已有 accept-inline verification matrix -- [ ] 验证证据中没有 unresolved failed / blocked items -- [ ] 没有把功能性核心路径未验证、真实用户/API/运行时路径未运行、必跑命令未执行写成 residual-risk 后放行；非功能性 feature 的替代证据理由已复核 -- [ ] 第 1/2 节核对全部勾选，无未处理偏差（含挂载点 grep + 拔除沙盘推演） -- [ ] 第 3 节场景核对全部勾选；功能性前端已浏览器验证，非功能性前端已有替代证据 -- [ ] 第 4 节术语一致性无遗漏 -- [ ] 第 5 节领域影响盘点：每条候选有明确结论（已建议 cs-domain / 不需要） -- [ ] 第 6 节 req 回写有结论：跳过 / 未变 / 已 backfill / draft→current / 已 update -- [ ] 第 7 节 roadmap 回写有结论：跳过（非 roadmap 起头）/ 已更新（items.yaml + 主文档同步，yaml 通过校验） -- [ ] checklist 所有 checks 都 `passed` -- [ ] 最终审计已完成：聚合命令重跑、完整工作区复核、交付物落盘复核、diff 清洁度复核、知识沉淀出口分流、re-verified / trust-prior-verify 已记录；无未处理缺口 -- [ ] 用户终审确认 - ---- - -## 退出后 - -告诉用户："验收报告已就绪，领域影响候选已盘点，cs-feat 工作流走完。后续 BUG 走 issue 流程。" - -按 `shared-conventions.md` 第 3 节收尾推荐顺序逐项一句话提示（用户说"不用"立刻跳过）： - -1. 复用价值的坑点 / 经验 / 长期约束 / 技术选型 → "沉淀到 compound？（`cs-keep`）" - - **特检**：design 第 2.5 节是否有"建议沉淀的 convention"段。有就把那条规则原文念给用户："design 2.5 建议沉淀这条 convention：『{规则一句话}』，跑通了，要不要现在 `cs-keep` 归档？"——这种是 design 阶段就识别出的稳定模式，比一般"问问看"更应该主动提 -2. 接口变更 / 用户可见行为变更 → "需要更新指南吗？（`cs-doc-tutorial`）" -3. 库公开接口（组件 / 函数 / 命令）变了 → "需要更新 API 参考吗？（`cs-doc-api`）" -4. 第 8 节有 attention.md 候选 → 逐条问"候选 X 加到 attention.md 吗？" 用户明确同意 → 触发 `cs-note` 走分节归类 / 查重 / 软上限检查（不在 accept 里手写，避免和 cs-note 各搞一套口径）；**一次一条** -5. 阶段 / 里程碑收尾、准备交接，或本次改动影响 README/docs、`CLAUDE.md` / `AGENTS.md`、agent 记忆 → "要做一轮文档与记忆整理吗？（`cs-docs-neat`）" -6. 最后问是否代为 scoped-commit - -收尾提交规则看 `shared-conventions.md` 第 4 节。提交范围：功能代码 + 方案 doc + 验收报告 + 本次实际更新的 req doc / CONTEXT.md / ADR / roadmap items.yaml + 主文档。 - ---- - -## 容易踩的坑 - -常见坑（测试/QA passed ≠ 验收场景满足、挂载点要 grep 不能只看清单、领域盘点是当下动作不是建议、accept 不直接改 CONTEXT.md 或写 ADR——那是 cs-domain 的事，accept 只盘点 + 建议、final audit 缺口要先修不能写"遗留"、accept 不自由重写 requirement 必须走 delta、未经用户终审 / 同意不宣告完成或 commit 等）见同包 `reference.md`。 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-feat` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-feat-design-review/SKILL.md b/plugins/codestable/skills/cs-feat-design-review/SKILL.md index 5150297..21e09cf 100644 --- a/plugins/codestable/skills/cs-feat-design-review/SKILL.md +++ b/plugins/codestable/skills/cs-feat-design-review/SKILL.md @@ -1,290 +1,23 @@ --- name: cs-feat-design-review -description: Feature design review gate。触发：人审前审 design/checklist，或用户要求方案审查。 +description: Feature design-review 兼容入口。旧调用保留；执行时转入 cs-feat 主流程的 design-review 阶段。 --- # cs-feat-design-review -## 启动必读 +本技能是 `cs-feat` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_stage: design-review` -本阶段是 feature design 交给用户人工确认前的方案审查 gate。它只读 design、checklist、相关文档和必要代码事实，只写 `{slug}-design-review.md`，不直接改 design/checklist、不替用户批准 design、不进入实现。 +## 执行规则 -目标不是替用户做产品判断，而是确认这份 design 已经具备让用户有效 review 和让下游稳定执行的条件：需求边界可核对、名词层和编排层有代码事实支撑、steps 可独立验证、checks 能回到 design 证据、风险 / 基线 / 交付物 / 清洁度可被后续 implement、code review、QA 和 acceptance 消费。 +1. 按已安装 skill 名称加载 `cs-feat` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-feat` 主协议继续执行，并带上入口意图 `requested_stage: design-review`。 +3. 不要要求用户重新调用 `cs-feat`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。feature design 的具体结构以目标 `{slug}-design.md` / `{slug}-checklist.yaml` 和项目内共享口径为准。 -> 报告语言：design-review 报告正文必须按 `.codestable/attention.md` 用**中文**；若草稿用了英文，落盘前先改写为中文。frontmatter / yaml 字段不翻译。 +## 维护规则 ---- - -## 输入 - -进入 review 前必须读取： - -- `.codestable/attention.md` -- `.codestable/features/{feature}/{slug}-design.md` -- `.codestable/features/{feature}/{slug}-checklist.yaml` -- 同目录的 `{slug}-intent.md` / `{slug}-brainstorm.md`（如果存在） -- design frontmatter 指向的 requirement 文档 -- design frontmatter 指向的 roadmap 主文档和 items.yaml（如果有 `roadmap` / `roadmap_item`） -- design 第 4 节指向的 architecture 文档 -- 相关 compound 沉淀：用项目搜索工具按 feature 关键词检索 decision / learning / explore / trick -- design 中引用到的关键代码位置、接口、类型、组件、命令、配置 -- 独立 Task agent reviewer 输出（如果本轮已启动） - -没有代码引用时不强行扫全仓库；但 design 声称复用、修改、挂载或约束某个现有模块时，必须读对应代码或文档事实核验。 - ---- - -## 启动检查 - -1. design 存在，frontmatter `doc_type=feature-design`，`feature` 与目录一致，`status` 通常是 `draft`；复审已 approved 设计时要确认用户确实要求重新审查。 -2. checklist 存在，`feature` 与目录一致，`steps` 非空，`checks` 非空；缺 checklist 时报告 `blocked`，回 `cs-feat-design` 生成 review candidate checklist。 -3. checklist 的 `steps.status` 和 `checks.status` 在人审前都应是 `pending`；已有 `done/passed` 说明阶段混乱，报告 `blocked`。 -4. 从 roadmap 起头时，roadmap item 必须能在 items.yaml 中找到，design 的 `roadmap_item` 与 feature slug 对齐。 -5. 如果已有 `{slug}-design-review.md`： - - `status: passed` 且 design/checklist 未变化：提示可进入用户整体 review。 - - `status: changes-requested` / `blocked`：读取旧 findings，确认是否复审。 - - design/checklist 已变化：重新 review，并在报告里记录轮次。 - ---- - -## 独立 Task agent reviewer gate - -本阶段必须优先启动独立 Task agent reviewer；当前 agent 的本地审查只能作为合并与事实核验，不能替代独立审查。只有运行时确实没有 Task agent 能力、provider 不可用且无法配置，或用户在看到降级风险后明确授权，才允许 `local-only` / `skipped-by-user`。批量 design、赶时间、主 agent 自认为风险低，都不是降级理由；需要授权降级时，先按 `.codestable/reference/approval-conventions.md` 写 `approval-report.md`，再让用户选择。 - -一旦本轮应该启动或已经启动独立 Task agent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 reviewer 返回前定稿 `{slug}-design-review.md`、不能给出 `passed`、不能把 design 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。 - -**检测由主 agent 在运行时自检自己的工具**，不靠脚本猜环境——主 agent 最清楚自己手上有哪些工具。按 Task agent 选择规则启动独立 Task agent reviewer（优先 Paseo subagent，否则当前宿主原生 Codex/Claude Task/Agent）： - -1. **有 `mcp__paseo__create_agent` 工具**：必须优先用 Paseo subagent 做只读独立审查（首选：能换 provider，做到真正异构审查）。启动前先加载 / 读取 `paseo` skill 的当前说明，并遵守它的规则：读取 `~/.paseo/orchestration-preferences.json`，使用 `providers.audit`，不要硬编码 Claude 或 Codex。不要无限轮询运行中的 agent；如果 reviewer 已启动但结果未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。 -2. **否则有当前宿主原生 Codex/Claude Task/Agent 工具**：用原生 Task agent 做独立上下文审查。如属同类 agent，在报告里记录降级和残余风险。 -3. **两者都没有**：本地 review 只能在记录 `local-only` 且获得必要授权后定稿；没有授权时报告 `blocked`，不要伪装启动。 - -独立 Task agent reviewer prompt 必须只给原始材料和边界，不透露本地 review 结论： - -```text -你是 CodeStable feature design 的独立方案审查 agent。只读，不修改文件，不更新 design/checklist。 - -请读取： -- .codestable/attention.md -- {design_path} -- {checklist_path} -- 同目录 intent / brainstorm（如有） -- 相关 roadmap / requirement / architecture / compound 文档 -- design 引用到的关键代码、接口、类型、组件、命令入口 - -按 cs-feat-design-review 的严重度语义输出：blocking / important / nit / suggestion / learning / praise / residual-risk。 -重点审查：需求边界、术语冲突、名词层现状→变化、module interface depth / seam / adapter、编排层流程、挂载点可卸载性、结构健康度、验收契约、steps 原子性、checks 来源、基线与验证命令、交付物、清洁度、roadmap 接口契约遵守情况。 -每条 finding 必须有 design/checklist/doc/code 事实证据、影响、建议修复边界。 -不要写 {slug}-design-review.md；只把审查结果回传给主 agent。 -``` - -主 agent 仍是最终审查责任方：必须逐条核验独立 Task agent reviewer 的 finding，去重、定级、合并进 `{slug}-design-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。 - ---- - -## 审查流程 - -### 1. 范围与事实 - -- 用 design 第 0/1 节确认术语、需求摘要、明确不做、复杂度档位、关键决策。 -- 用第 2.1 / 2.2 节确认名词层和编排层是否都有"现状 → 变化"，且现状指向真实代码 / 文档。 -- 用第 2.3 节确认挂载点是否按"删掉 feature 是否消失"收紧。 -- 用第 2.4 节和 checklist steps 对齐推进策略、退出信号和验证动作。 -- 用第 2.5 节确认结构健康度评估覆盖文件级 + 目录级，微重构只做"只搬不改行为"。 -- 用第 3/4 节确认验收契约、架构回写预判、证据类型。 -- 从 roadmap 起头时，额外核对 roadmap 第 4 节接口契约是硬约束，design 没有私自绕开。 - -### 2. 独立审查合并 - -- 记录主 agent 自检结果：`paseo` / `native-agent` / `local-only`。 -- 没有启动独立 Task agent reviewer 时，记录确无能力 / provider 不可用 / 用户授权降级；未满足这些条件时不得定稿 `passed`。 -- 启动 Paseo subagent / 原生 Task agent 后，最终 verdict 必须等 reviewer 返回。 -- reviewer 返回后逐条做本地事实核验；能用 design / checklist / 文档 / 代码证据支撑才合并。 -- reviewer 失败、权限阻塞、超时或仍在运行时，不要默默降级；报告 `status: blocked`。 - -### 3. 方案审查 - -至少覆盖： - -- 需求边界：用户目标、核心行为、成功标准、明确不做是否可核对。 -- 术语与现状：关键术语是否与代码 / 架构 / 历史 feature 冲突；现状描述是否真实。 -- 名词层：值对象、实体、接口、类型、组件 props/events 是否讲清变化。 -- Module/interface 设计：interface 是否包含 caller 必须知道的 invariant / ordering / error mode；module 是否 deep；seam / adapter 是否真实需要；测试是否能通过 interface 观察行为。 -- 编排层：主流程图、分支、错误语义、幂等、并发、可观测点是否能跑通。 -- 挂载点：是否列了真实对外注册点，而不是内部改动文件清单。 -- 结构健康度：微重构是否必要且边界安全；目录 convention 候选是否合理。 -- 验收契约：正常 / 边界 / 错误路径是否覆盖，是否有证据类型。 -- checklist：steps 是否独立可验证，exit_signal 是否 yes/no，checks 是否都能追溯到 design。 -- 基线与验证：必跑命令、预检策略、基线红灯归因是否写清。 -- 交付物与清洁度：acceptance 是否能从仓库事实核验；调试输出、TODO、死 import 等规则是否明确。 - -### 4. Feature Design Review Invariants 与证据分级 - -每轮 review 必须形成 Evidence Confidence Ledger。证据分级只描述依据来源，不计算质量分： - -- `E` Embedded：design / checklist / roadmap item / 命令输出里直接可见。 -- `C` Context：相关 req / arch / compound / 代码事实支撑。 -- `H` Heuristic：工程经验或 reviewer 判断，缺少直接仓库证据。 - -核心 invariants： - -- Acceptance Coverage Matrix 覆盖每个核心验收场景。 -- 每个核心场景能追踪到 checklist step、证据类型和命令 / 动作。 -- checklist steps 独立可验证，checks 能回到 design 来源。 -- roadmap 起头的 design 没有绕开 roadmap 接口契约。 -- DoD Contract 覆盖 Design / Implementation / Review / QA / Acceptance DoD、Validation Commands 和 Required Artifacts。 -- Module/interface design 覆盖 depth、seam placement、dependency strategy；没有新增 / 改动 interface 时可标 not-applicable。 -- checklist `dod.commands` 若存在，字段使用 `{id, command, core, failure_handling}`；design 表格只是人读投影。 -- 核心检查若只有 `H` 证据，不能静默 `passed`；至少写入 residual risk，必要时列 important / blocking finding。 - ---- - -## 严重度 - -- `blocking`：必须先修。会导致 design 不能被用户有效 review、实现无稳定契约、roadmap 契约被绕开、steps/checks 无法执行、验收不可证伪、关键风险没有验证路径。 -- `important`：应该修；若用户决定延后，必须在 design review 和用户 review 摘要中明确记录。 -- `nit`：小的清晰度或一致性建议，不阻塞。 -- `suggestion`：替代设计思路或补强建议，不要求本次采用。 -- `learning`：知识性说明，不要求动作。 -- `praise`：记录值得保留的设计做法；少量即可。 -- `residual-risk`：review 无法完全消除的不确定性，需要用户 review、implementation、code review、QA 或 acceptance 重点复核。 - -不要把个人偏好的实现写法升级成 blocking。blocking 必须能用 design 契约、checklist、roadmap/req/arch、代码事实或可靠工程原则支撑。 - ---- - -## 报告模板 - -报告路径：`.codestable/features/{feature}/{slug}-design-review.md`。 - -```markdown ---- -doc_type: feature-design-review -feature: {feature} -status: passed|changes-requested|blocked -reviewed: YYYY-MM-DD -round: 1 ---- - -# {slug} feature design 审查报告 - -## 1. Scope And Inputs - -- Design: {path} -- Checklist: {path} -- Intent / brainstorm: {path / none} -- Roadmap: {path / none} -- Related docs: {requirements / architecture / compound} -- Code facts checked: {paths / none} - -### Independent Review - -- Status: not-available|skipped-by-user|local-only|pending|completed|failed|blocked -- Detection: paseo|native-agent|local-only|skipped -- Provider / agent: {providers.audit / agent id / none} -- Raw output: {摘要 / 路径 / none} -- Merge policy: {已逐条核验 / 未启用原因 / pending 时不得定稿} -- Gate effect: {none | blocks final verdict until completed / user-approved downgrade} - -## 2. Design Summary - -- Goal: {摘要} -- Key contracts: {名词层 / 编排层摘要} -- Steps: {数量 + 风险热点} -- Checks: {数量 + 来源完整性} -- Baseline / validation: {摘要} - -## 3. Findings - -### blocking - -- [ ] FDR-001 `{path#section|checklist.step|file:line}` {问题} - - Evidence: {事实} - - Impact: {为什么阻塞用户 review / implement} - - Expected fix scope: {修复边界} - -### important - -- [ ] FDR-00N `{证据位置}` {问题} - - Evidence: {事实} - - Impact: {影响} - -### nit - -- [ ] FDR-00N `{证据位置}` {建议} - -### suggestion - -- [ ] FDR-00N {建议} - -### learning - -- {可复用设计经验或注意点} - -### praise - -- {值得保留的做法} - -## 4. User Review Focus - -- 用户需要重点拍板：{决策 / 假设 / 不做范围} -- implement 需要重点遵守：{契约 / steps / 验证} -- code review / QA / acceptance 需要重点复核：{风险 / 证据} - -## 5. Evidence Confidence Ledger - -| Check | Verdict | Evidence Class | Basis | Follow-up | -|---|---|---|---|---| -| Acceptance Coverage Matrix | pass|warn|fail | E|C|H | {路径 / 事实 / 判断依据} | {none / 复核点} | -| DoD Contract | pass|warn|fail | E|C|H | {依据} | {复核点} | -| Steps and checks traceability | pass|warn|fail | E|C|H | {依据} | {复核点} | -| Roadmap contract compliance | pass|warn|fail | E|C|H | {依据} | {复核点} | -| Module interface design | pass|warn|fail|n/a | E|C|H | {依据} | {复核点} | -| Validation and artifacts | pass|warn|fail | E|C|H | {依据} | {复核点} | - -Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。 - -## 6. Residual Risk - -- {风险 + 下游如何处理；没有写 none} - -## 7. Verdict - -- Status: passed|changes-requested|blocked -- Next: 交给用户整体 review | 回 `cs-feat-design` 修订后重跑 `cs-feat-design-review` | 等独立 Task agent reviewer 完成 / 用户确认降级后重跑 -``` - -没有某类 finding 时写 `none`，不要删除章节；下一轮复审要能对比。 - ---- - -## 退出条件 - -- [ ] 已读取 attention、design、checklist、相关 intent / brainstorm / roadmap / req / arch / compound。 -- [ ] 已按 design 声明核验必要代码、接口、类型、组件或命令事实。 -- [ ] 已确认 checklist 可解析，steps/checks 都可追溯。 -- [ ] 已按 Task agent 选择规则启动独立 reviewer；若未启动，已记录确无能力 / provider 不可用 / 用户授权降级。 -- [ ] 如果启动了独立 Task agent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。 -- [ ] 已审查需求边界、术语、名词层、编排层、挂载点、结构健康度、验收契约、steps/checks、基线、交付物、清洁度。 -- [ ] 已检查 Acceptance Coverage Matrix、Feature Design Review Invariants 和 Evidence Confidence Ledger。 -- [ ] 核心检查 H-only 时没有静默 passed。 -- [ ] 已写 `.codestable/features/{feature}/{slug}-design-review.md`。 -- [ ] 有 blocking / 未处理 important 时指向 `cs-feat-design` 修订并重跑 review。 -- [ ] 无 blocking 且 important 已处理或明确接受时，明确告诉用户下一步是 feature design 人工 review。 - ---- - -## 容易踩的坑 - -- 把 design review 做成文案润色，没审 steps/checks 是否能执行。 -- 只读 design，不核对 checklist 来源。 -- roadmap 起头时不检查接口契约，导致 feature 偷偷绕开 roadmap。 -- 现状段没读代码就放过，implement 阶段才发现设计站不住。 -- steps 出现"和 / 以及 / 同时"却不复查是否该拆。 -- 把批量 design 或赶时间当成 local-only 降级理由。 -- 启动独立 Task agent reviewer 后结果还没回来，就把本地 review 定稿为 passed。 -- 外部 reviewer 的结论没经本地事实核验就照抄。 -- review 报告没有落盘，导致用户 review 和后续实现没有可追溯输入。 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-feat` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-feat-design/SKILL.md b/plugins/codestable/skills/cs-feat-design/SKILL.md index 8ec9d04..287a927 100644 --- a/plugins/codestable/skills/cs-feat-design/SKILL.md +++ b/plugins/codestable/skills/cs-feat-design/SKILL.md @@ -1,281 +1,23 @@ --- name: cs-feat-design -description: Feature design。触发：新功能已清楚，需要起草 design/checklist。 +description: Feature design 兼容入口。旧调用保留；执行时转入 cs-feat 主流程的 design 阶段。 --- # cs-feat-design -## 启动必读 +本技能是 `cs-feat` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_stage: design` -这一阶段的产出是一份方案文件 `{slug}-design.md`，加上从中抽出的行动清单 `{slug}-checklist.yaml`，以及人审前的 `{slug}-design-review.md`。这些东西后面会被 implement / code review / QA / acceptance 消费，所以这里写错或写漏，下游就跟着错。 +## 执行规则 -> 共享路径和命名约定看 `.codestable/reference/shared-conventions.md`。本阶段一般 feature 目录已经由 brainstorm 创建好了；没有的话在这一步建。 -> 报告语言：design / plan 正文必须按 `.codestable/attention.md` 用**中文**；若草稿用了英文，落盘前先改写为中文。frontmatter / yaml 字段不翻译。 +1. 按已安装 skill 名称加载 `cs-feat` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-feat` 主协议继续执行，并带上入口意图 `requested_stage: design`。 +3. 不要要求用户重新调用 `cs-feat`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -本阶段有三个入口： +## 维护规则 -- **正式起草**：用户已经能讲清楚需求（或已经填好 `{slug}-intent.md`），直接进"流程"一节走完整起草。 -- **初始化模式**：用户说"开一个新需求 / 起个草稿 / 新建一个 feature"，但想自己先写半成品方案而不是口述。走下一节"初始化模式"，建好目录和空 `{slug}-intent.md` 就结束本轮，等用户填完再回来。 -- **从 roadmap 条目起头**：用户说"开始做 roadmap 里的 {子 feature slug}"或"推进 {roadmap} 的下一条"。slug 从 roadmap items.yaml 取，不另起；动笔前要读 roadmap 主文档和 items.yaml 了解上下文和依赖状态；落盘时 frontmatter 要带 `roadmap` / `roadmap_item` 两个字段，同时回写 items.yaml 把对应条目 `status` 改为 `in-progress`、`feature` 填为 feature 目录名。详见下文"从 roadmap 条目起头"。 - -**设计原则**：design 不是实现前的散文说明，而是后续实现和验收的可执行契约。它必须把"做好"翻译成可观察证据，把 steps 切成独立可验证单元，把风险和依赖前置暴露，并在交给用户前做一次自我批判，修掉含糊标准、混合步骤和薄弱依赖。 - -**推进原则**：design 要把后续执行需要的"操作手册"写到位：当前基线怎么确认、每步完成后看什么证据、哪些命令必须重跑、哪些交付物要真实落盘、失败时回到哪个契约修。否则 implement 只能临场判断，review 没有稳定契约可审，QA 不知道该跑什么证据，acceptance 也只能相信实现汇报。 - ---- - -## 初始化模式：帮用户建目录和 intent 草稿 - -触发：用户想自己写一份半成品方案（`{slug}-intent.md`）作为后续 design 的输入，但不想手动建目录。 - -动作： - -1. **和用户快速对齐两件事**——一句话需求概要 + 敲定 slug（小写字母、数字、连字符；`user-auth`、`export-csv` 这种）。日期取当天（frontmatter 用 `currentDate` 即可）。feature 目录命名是 `YYYY-MM-DD-{slug}`。 -2. **创建 `.codestable/features/{YYYY-MM-DD}-{slug}/` 目录**。 -3. **写一份空的 `{slug}-intent.md`** 作为草稿骨架，模板见 `references/intent-template.md` - 的“feature intent 草稿模板”。 - -4. **告知用户"骨架已建好，填完后再来找我，我基于 intent 写正式 design"**，然后**本轮结束，不继续推进 design 流程**。 - -为什么在这里停？intent 的价值就是让用户离线思考、把脑子里的东西落到纸面。AI 继续问会把 intent 模式退化成 brainstorm，失去意义。 - ---- - -## 从 roadmap 条目起头 - -触发：用户说"开始做 roadmap 里的 {子 feature}"或指向 items.yaml 里某条 `planned` 条目。 - -1. **读 roadmap 上下文**——打开 `{roadmap-slug}-roadmap.md` 和 `{roadmap-slug}-items.yaml`： - - 目标条目必须 `status: planned` + `depends_on` 前置全 `done`，否则停下来报告 - - **必读主文档第 3 节"模块拆分"和第 4 节"接口契约 / 共享协议"**——这是本 feature 的硬约束输入。契约不合理 / 漏了 → 停下来建议回 `cs-roadmap update` 改，**不要在 design 里偷偷绕开** -2. **slug 从 roadmap 取**，feature 目录 `YYYY-MM-DD-{roadmap 条目 slug}`，不另起 -3. **走"流程"一节**，frontmatter 加 `roadmap` / `roadmap_item` 两字段 -4. **候选落盘时回写 items.yaml**：对应条目 `status: in-progress` + `feature: YYYY-MM-DD-{slug}`，用 `validate-yaml.py` 校验；design 先保持 `status: draft`，通过 `cs-feat-design-review` 且用户确认后才改 `approved` - -完整衔接协议看 `.codestable/reference/shared-conventions.md` 第 2.5 节。 - ---- - -## design 写什么、不写什么 - -design 只管"编排-计算分离"里的编排那一侧：**这次 feature 在名词层和编排层的现状与变化**。计算层细节（具体怎么写、改哪些函数、测试怎么搭）归 implement。 - -写三类东西，名词层和编排层都用"**现状 → 变化**"两段式： - -1. **名词层**——值对象 / 实体 / 数据结构 / 对外契约 / 类型定义 -2. **编排层**——主流程 / workflow / 关键编排函数 / 控制流拓扑（线性 / 分支 / 并行 DAG / 状态机）。开头一张主流程图建 mental model -3. **流程级约束**——错误语义、幂等性、并发 / 顺序、扩展点位置、可观测点。挂载点清单也归这类 - -当本 feature 引入或改变 module interface、seam、adapter、跨依赖测试策略时，按 `references/codebase-design.md` 做内嵌 deep-module 检查；这不是切换到独立 `codebase-design` skill。 - -外加一个**固定结构健康度环节**（第 2.5 节）：评估即将被改动的文件是否偏胖 / 职责混杂、以及新文件要落进的目录是否摊平，决定是否在实现前先做"只搬不改行为"的微重构（拆文件 / 重组目录）。即使结论是"不做"也要在 design 里显式写出来——否则 AI 默认会持续往胖文件里塞代码、往拥挤目录里加文件。这一节随整稿一起进整体 review，不单独走确认。 - -**判据**：换一种写法名词层或编排层会变得不同 → design 的事；换一种写法只是"代码不那么好看 / 函数拆法不同 / 测试用了别的 framework" → implement 的事。 - -不写改动文件清单、函数级落点、测试代码、库选型细节——design 阶段还没读完相关代码，预测多半会回头改。implement 拿到 design 后才扫现状决定。 - ---- - -## 方案文件是给人概览的，不是给人仔细阅读的 - -读者打开 `{slug}-design.md` 是想 5 分钟内抓到要点，不是逐字精读。具体做法： - -1. **每节超过 1 屏就砍或拆**——一屏装不下读者会失去定位 -2. **术语先锁死**——动笔前 grep 代码 / 架构 / 历史 feature 防冲突，事后理顺成本远高于预防 -3. **示例优先于定义**——接口行为先给"输入→输出"示例，复杂时再补正式类型 -4. **同一条信息只在最自然的位置出现一次**——重复表述比缺一条还烦 -5. **新逻辑默认放新文件**（写在改动计划里）——文件越大越难分清职责 - ---- - -## 起草时的三条纪律 - -### 1. 别替用户做决定 - -碰到"用户没说清的角落"默认停下来问，不自己挑一个填上去。具体： - -- **声明假设**：非用户原话的判断写成"假设：……"，让用户能精确反驳 -- **给选项不自选**：2-3 种合理做法都摆出来再讲倾向 -- **看不懂就停**：硬猜着写下去到了 acceptance 阶段对不上验收点 - -### 2. 目标和约束都写成可验证的 - -- 不写"让它能跑"、"用户体验顺畅"这种弱标准——改写成"输入 A 时返回 B" -- "明确不做"具体到能被 grep 或测试反向核对，不写"不过度设计"这种空话 - -### 3. 每个 feature 都要能被卸载 - -回答："如果想把它拔掉，要拔哪些地方？" 答不出说明边界没想清楚，feature 一上线就变成拆不动的既成事实。 - -落到挂载点清单（第 2.3 节）。**判据**：删掉这一项，feature 在用户/系统视角是不是就消失了？是→列，否→不列。详细 ✅/❌ 例子和写法看 reference.md。这清单顺带帮你发现自己有没有不小心往太多地方插桩——真挂入点越多代表耦合越散，是个信号。 - ---- - -## 流程：什么时候做什么 - -### 1. 启动检查 - -**前置 gate**：需求输入至少含 用户目标 / 核心行为 / 成功标准 / 明确不做 四项（来源 intent / brainstorm / 对话）。缺了补；用户自己说不清就回退到 brainstorm。 - -**必做 4 条**： - -1. **续作检查**——Glob `{slug}-design.md` / `{slug}-intent.md` / `{slug}-brainstorm.md`： - - intent / brainstorm：当作输入读入，不重复问已讲清的部分 - - design `status=draft` 各节基本完整 → 若 checklist 存在则跳到本流程"5. 独立 design review gate"，否则先生成 checklist - - design 部分节缺失 → 补缺失节，汇报"上次写到 X，补齐统一给你 review" - - design `status=approved` → 别默认覆盖，问用户接着改还是另起 slug -2. **扫 .codestable/ 全局输入**——Glob `.codestable/` 发现可用目录和文档类型，按类取用： - - `requirements/CONTEXT.md` → 读领域术语表，用项目术语命名，不自己造名 - - `requirements/adrs/` → 跨模块或流程级约束相关的 ADR 必读；命中和方案冲突的 ADR **必须**正面回应"为什么仍然这么做"或调整方案 - - `requirements/{slug}.md` → 有对应 req：frontmatter `requirement` 填 slug，读"用户故事 / 边界"两节；新能力首次出现 → 触发 `cs-req draft` 起草愿景 req，frontmatter `requirement` 填新 slug；纯重构 / 技术债留空 - - `compound/` → `grep -r "关键词" .codestable/compound/` 搜历史沉淀；命中相关坑点 / 写法约束就融进方案 - - `features/` → 搜历史 design 有无同类 feature 可参考 - - 其余目录按内容类型自行判断 -3. **读需求相关的现有代码**——读哪些文件由需求线索决定 -4. **识别验证基线**——从 attention / README / package scripts / CI / 历史 acceptance 里找本 feature 应用的 build / typecheck / lint / test / e2e / 浏览器验证入口；如果命令当前可能已红，写入第 1 节"基线风险"，implement 开始前要先做轻量预检，避免把既有红灯误算成本 feature 失败 - -**按信号触发 3 条**（没信号跳过）： - -- **术语 grep 防冲突**——新概念名没在代码 / 架构 / 历史 feature 里见过时，grep 一遍；冲突就换名或在第 0 节明确区分 -- **复杂度档位对齐**——需求里出现"对外 SDK / 高并发 / 一次性工具"等偏离信号时，打开 `.codestable/reference/code-dimensions.md` 列偏离点；无信号写"走默认档位" -- **grep 找"叫法不同的类似模块"**——直觉"可能已有人做过但命名不同"时，grep 同义词 - -详细规则看 `.codestable/reference/shared-conventions.md` 第 5 节。 - -### 2. 想清楚这功能该放在哪儿 - -动笔写名词层 / 编排层前，先回答：**这次要加的东西在项目整体结构里属于哪儿？** - -- 现有模块本该承担？→ 在那个模块里扩展，别另起 -- 横跨多个模块？→ 抽公共层 vs 让某一方主导、其他方依赖 -- 跟现有任何模块都不像？→ 新建独立模块/子系统，对外暴露什么、跟别人怎么交互提前想清楚 -- 可能已有模块在做类似的事但叫法不同？→ grep 几个同义词 - -代价：放错了模块就变"什么都装的筐"；新建平行实现就有几个版本同存。 - -结论写进第 1 节"决策与约束"。涉及新建模块或跨模块接口时，提示用户走 `cs-domain` 起一条 ADR 记下这个结构性决策。 - -AI 默认翻车的姿势是**不思考就往眼前最顺手的文件里加**。 - -### 3. 写"现状 → 变化"两段式的名词层和编排层 - -按 reference.md 模板写第 2 节四个子节（2.1 名词层 / 2.2 编排层 / 2.3 挂载点 / 2.4 推进策略）。重点提示： - -- "现状"必须指向代码位置，不能想当然——读者要靠它判断"变化"是否合理 -- 触碰 module interface / seam / adapter 时，补 `references/codebase-design.md` 里的 Interface 设计检查 -- 编排层开头一张 mermaid 图建 mental model -- 挂载点按"删了它 feature 是否消失"判据，3-5 条为正常区间 -- 推进策略按 paradigm 维度切片（编排骨架 → 计算节点 → 持久化 → 测试），不下沉到 file:line -- **第 2.5 节"结构健康度与微重构"是固定步骤**——按 reference.md 写作要求评估**两类对象**：要改的文件（文件级）+ 要落新文件的目标目录（目录级）。**评估前先查 compound 已有 convention**（关键词围绕"目录组织 / 文件归属 / 命名约定"），命中就直接照办。结论三选一： - 1. **不做**——文件健康 / 目录不挤 / 改动量小 / 微重构收益不抵风险，写"本次不做微重构，原因：……" - 2. **做微重构（拆文件）**——文件偏胖或职责混杂但能用 provable refactor（拆函数 / 拆文件 / 移动定义，编译器全程绿灯）解决 - 3. **做微重构（重组目录）**——目标目录摊平且能通过纯文件移动 + import 路径更新解决（编译器全程绿灯） - - 选择 2 / 3 时给出"搬什么 → 搬到哪 → 怎么验证行为不变"的具体方案，落进 checklist 作为**第 1 步且独立验证退出**，再开始 feature 主体 -- **重组目录时多问一步：是稳定模式还是一次性整理**——稳定模式（如"自定义业务组件统一放 `components/custom/`"，未来其他 feature 也该遵守）就在 2.5 末尾加"建议沉淀的 convention"段，提示用户 implement 跑通后走 `cs-keep` 归档；一次性整理（只是这个目录碰巧挤了）就只搬不归档。**design 阶段不直接归档**——方案还没真跑过，留钩子给 implement 后再决定 -- **design 只做安全的微重构，边界严格守住**："只搬不改行为"——文件级靠 IDE rename / move + 编译器校验，目录级靠纯文件移动 + import 路径更新 + 编译器校验。一旦涉及改函数签名 / 改返回值结构 / 改调用关系语义 / 模块拆合，就**超出 design 范围**：写进第 2.5 节末尾的"超出范围的观察"里提示用户"建议后续走 `cs-refactor` 处理"，**不阻塞本 feature、不作为前置依赖**。是否真去做、什么时候做由用户在 feature 之外决定 -- **第 2.5 节随整稿一起 review，不单独确认**——和功能方案打包给用户一次过，避免拆成两轮把节奏拖长 - -### 4. 补齐剩下各节，生成 review candidate - -按 reference.md 模板补齐剩余节（第 0 / 3 / 4 节）。初稿 frontmatter `status: draft`。 - -整稿成型后先确认正文语言符合 `.codestable/attention.md`（默认中文；英文草稿先改写），再落盘 draft design，并从 `{slug}-design.md` 抽出 candidate `{slug}-checklist.yaml`。checklist 的 steps/checks 初始都保持 `pending`，用 `validate-yaml.py` 校验。不要等用户确认后才生成 checklist，因为人审前的 `cs-feat-design-review` 需要同时审 design 和 checklist 是否对齐。 - -第 3 节"验收契约"提示：每条写成"输入 / 触发 → 期望可观察结果"，覆盖正常 + 边界 + 错误，并补 `Acceptance Coverage Matrix` 和 `DoD Contract`；完整模板看 reference.md。 - -**补一段执行风险与证据计划**（写进第 1 节或第 2.4 节，按文档自然位置放）： - -- **Top 3 风险**：最可能实现偏、最难回滚、最容易验收遗漏的三点；每点写对应缓解（某个 step、某条验收场景、某个先验命令） -- **非显然依赖**：外部服务、数据迁移、现有模块顺序、用户拍板项；说明阻塞哪个 step -- **证据类型**：每个验收场景最终靠什么证明（类型 / 单测 / 集成 / 手工 / 浏览器截图 / API 响应 / diff review） -- **关键假设**：不是用户原话但方案依赖它成立的判断，review 时让用户能改 -- **必跑验证命令**：本 feature 完成前必须运行哪些命令；命令可能基线已红时写清"预检先跑，红灯要分清既有问题 / 本次引入" -- **交付物清单**：最终应该新增 / 修改 / 删除的用户可见或系统可见产物类别（代码入口、配置 key、schema、路由、文档归并、roadmap 状态），acceptance 要按仓库事实反查 -- **清洁度规则**：本 feature 不允许新增的调试输出、临时 TODO/FIXME、注释掉代码、无用 import；如某类 debug 输出是功能本身，必须在 design 里显式说明例外和范围 - -**steps 写法原则**： - -- 步数由工作自然切片决定，不为了凑 4-8 合并不相干内容；如果确实超过 8，先检查是不是应该退回 roadmap 拆子 feature -- 每步交付一件 coherent thing，能独立验证；名字里出现"和 / 以及 / 同时"时复查是否该拆 -- 每步 `exit_signal` 必须是 yes/no，可由命令、测试、截图、接口响应、页面观察、类型检查或 diff review 证明 -- 每步要标出建议验证动作（命令 / 手工 / 浏览器 / diff review）和主要交付物类型，方便 implement 做 step 证据块 -- UI feature 最后必须覆盖可见状态与 polish：空态、加载、错误、禁用 / 未授权、长文本 / 小屏、focus / keyboard / contrast；如果不适用写明原因 -- 涉及安全 / 权限 / 输入处理 / 数据迁移时，最后一个功能 step 或单独 step 必须覆盖 harden：校验、越权、回滚、兼容、回归面 - -**交给用户前做一次自我批判**，并先在文档里修掉问题： - -1. **可证伪性**：第 3 节和 checklist 的每条是不是 yes/no？有没有"正常 / 完善 / 友好 / 稳定"这种无法核对的词？ -2. **步骤原子性**：有没有一个 step 塞了两件可以独立验收的事？有没有 step 只有下一步完成后才有意义？ -3. **最弱依赖**：哪个 step 出错会污染后续最多内容？是否需要提前验证、拆成独立 step、或补验收场景？ -4. **证据完整性**：每条关键场景是否都有证据类型？前端是否需要浏览器截图 / 肉眼验证？ -5. **基线可执行性**：必跑命令是否明确？如果命令当前可能已红，是否有预检和归因说明？ -6. **交付物可核验性**：acceptance 是否能从 git diff / 文件系统 / 配置 / 文档状态看到每个承诺产物？ -7. **清洁度覆盖**：是否明确禁止临时调试输出、TODO、死 import、注释掉代码，并说明必要例外？ -8. **接口深度**：新增 / 改动的 interface 是否给 caller 足够 leverage？seam 和 adapter 是否真实需要？ - -### 5. 独立 design review gate - -运行 `cs-feat-design-review`： - -- `passed`：才能把 design + checklist + design-review 报告交给用户整体 review。 -- `changes-requested`：按 finding 修 design/checklist，重新校验 yaml 并重跑 `cs-feat-design-review`。 -- `blocked`：补齐输入、等待独立 Task agent reviewer，或让用户明确降级 local-only 后重跑。 - -### 6. 用户整体 review - -发一次整体 review 提示（提示词在 reference.md 第 5 节），同时附上 Top 3 风险、关键假设、自我批判结论和 `{slug}-design-review.md` 摘要。用户提意见就改；如果修改影响名词层、编排层、验收契约、steps/checks、roadmap 契约或风险策略，必须同步更新 checklist 并回到 Phase 5 重跑 design review。用户明确放行后，把 `status` 从 `draft` 改 `approved`。 - -### 7. 确认 checklist - -确认 `{slug}-checklist.yaml` 已与最终 approved design 同步。完整格式、提取规则、典型节奏看 reference.md 第 3 节。 - -落盘后 `python .codestable/tools/validate-yaml.py --file {path} --yaml-only` 校验。 - -### 8. 退出 - -按下文退出条件核对，引导用户进入阶段 2。 - ---- - -## 退出条件 - -用户整体 review 通过，并且： - -- [ ] frontmatter 完整（`doc_type` / `feature` / `status=approved` / `summary` / `tags`），requirement 字段已对齐 -- [ ] design 正文已按 `.codestable/attention.md` 的报告语言落盘（默认中文；frontmatter / yaml 字段保持机读格式） -- [ ] 第 1 节含"不做什么"和复杂度档位偏离（或明确走默认） -- [ ] 第 2.1 / 2.2 用"现状 → 变化"两段式；接口有示例 + 来源位置；编排层开头有主流程图 -- [ ] 触碰 module interface / seam / adapter 时，已记录 depth / locality / seam / dependency strategy 检查结论 -- [ ] 第 2.3 挂载点按"删了它 feature 是否消失"判据收紧（一般 3-5 条） -- [ ] 第 2.4 推进策略按 paradigm 维度切片，每步有退出信号 -- [ ] 第 2.5 结构健康度评估覆盖文件级 + 目录级；评估前已查 compound convention；结论显式写出（不做 / 拆文件 / 重组目录）；选"微重构"时 checklist 第 1 步是它且有独立退出信号；选"重组目录"且属稳定模式时含"建议沉淀的 convention"段；超出"只搬不改行为"的结构性问题列在"超出范围的观察"，仅提示不阻塞 -- [ ] 第 3 节关键场景覆盖正常 + 边界 + 错误；含"明确不做"反向核对项；每条都有证据类型、Acceptance Coverage Matrix 和 DoD Contract -- [ ] Top 3 风险 / 非显然依赖 / 关键假设已写入 design 或 review 摘要 -- [ ] checklist steps 每步都能独立验证，exit_signal 是 yes/no；UI / 安全 / 迁移类 feature 已覆盖 polish / harden 或写明不适用 -- [ ] 已做可证伪性 / 步骤原子性 / 最弱依赖 / 证据完整性自我批判并修正问题 -- [ ] 必跑验证命令 / 基线风险 / 预检要求已写清 -- [ ] 交付物清单可被 acceptance 从仓库事实核验 -- [ ] 清洁度规则已写清：调试输出、临时 TODO/FIXME、注释掉代码、无用 import 的处理口径明确 -- [ ] `{slug}-design-review.md` 已通过 `cs-feat-design-review`，没有 unresolved blocking finding -- [ ] `{slug}-checklist.yaml` 已落盘并通过 `validate-yaml.py` 校验 -- [ ] roadmap 起头时 items.yaml 已回写（`status: in-progress` + `feature` 填上） - ---- - -## 容易踩的坑 - -- 没读相关架构 / 术语没 grep 就动笔——方案跟现有代码对不上、术语冲突后 git blame 找十倍时间 -- 用散文描述接口行为，没给具体示例——读者建不起模型 -- 名词层 / 编排层只写"变化"不写"现状"——读者无法判断变化是否合理 -- 把挂载点清单写成改动文件清单——内部改动归 implement，挂载点只列"删了它 feature 就消失"的登记条目 -- 在 design 写测试代码 / framework / mock / 函数级落点——这些归 implement 自决 -- 接口只写签名不写 invariant / ordering / error mode / seam rationale——implement 和测试会各自补语义 -- 强行画图——模块 ≤ 2 个、调用线性时画图反而模糊重点 -- 只给半份文档先 review——用户看不出全局一致性 -- 跳过 `cs-feat-design-review` 直接让用户拍板——用户只能看到方案表面，看不到 checklist、契约、验收策略的独立审查结论 -- 在需求摘要里偷偷扩范围——验收时对不上 -- 验收场景写成"体验良好 / 状态完整 / 逻辑正确"——acceptance 无法判定，只能靠感觉 -- checklist step 只有下一步完成后才能验证——说明切片不独立，执行中失败时无法定位 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-feat` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-feat-ff/SKILL.md b/plugins/codestable/skills/cs-feat-ff/SKILL.md index 7b4ae8e..1f89028 100644 --- a/plugins/codestable/skills/cs-feat-ff/SKILL.md +++ b/plugins/codestable/skills/cs-feat-ff/SKILL.md @@ -1,223 +1,23 @@ --- name: cs-feat-ff -description: Feature 快速通道。触发：快速模式/直接开干，且需求小到不值得 design。 +description: Feature fastforward 兼容入口。旧调用保留；执行时转入 cs-feat 主流程的 fastforward 模式。 --- # cs-feat-ff -## 启动必读 +本技能是 `cs-feat` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_mode: fastforward` -用户让你做小功能时本来 AI 就会直接动手——这个技能**不改变这件事**。它只做一件事：动手前把项目里已沉淀的 CodeStable 知识指给你，按需搜一下，写出来的代码就比裸写多一层保护；动手后回写一份**最简的 `{slug}-ff-note.md`** 让这次工作可追溯、可被 cs-req / cs-domain backfill 看到、能纳入 scoped-commit 提交。 +## 执行规则 -很轻：没有 design doc / checklist / 验收清单 / 动手前的用户确认。看完指引，该读代码读、该写代码写、写完回写一段话。 +1. 按已安装 skill 名称加载 `cs-feat` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-feat` 主协议继续执行，并带上入口意图 `requested_mode: fastforward`。 +3. 不要要求用户重新调用 `cs-feat`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 ---- +## 维护规则 -## 动手前先扫一眼 .codestable/ - -Glob `.codestable/` 发现可用目录和文档，按需取用： - -- **`requirements/CONTEXT.md`** — 领域术语；用项目术语命名，不自己造名 -- **`requirements/adrs/`** — 已拍板的架构决策；改跨模块的东西前 grep 相关 adr 避免违反 -- **`compound/`** — 沉淀的坑点 / 技巧 / 调研： - ```bash - grep -r "关键词" .codestable/compound/ - ``` -- **`requirements/{slug}.md`** — 有相关 req 时读边界 -- **`features/`** — 有同类 feature 时参考其 design -- **`reference/`** — shared-conventions.md / tools.md - ---- - -## 怎么用 - -动手前问 2 个问题： - -1. **这块代码以前有人栽过跟头吗？** → `grep -r "关键词" .codestable/compound/` -2. **这块代码有没有已经拍板的写法约束？** → 看 `requirements/adrs/` 相关 ADR + grep `compound/` 找写法沉淀 - -命中就把结论融进实现（**按约束来写**，不是抄）。没命中按自己判断写很正常。搜不到换几个关键词再试。 - ---- - -## 执行 gate（worktree + commit） - -fastforward 直接改项目源码且是快速通道末端，两道 gate 仍要走。slug 未定时先按动作敲定（见下文"自动生成 slug"），unit 路径用 `.codestable/features/YYYY-MM-DD-{slug}`。 - -动手前运行 start gate： - -```bash -python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/features/YYYY-MM-DD-{slug} -``` - -gate 不通过就不要开始改代码；用户批准 override 时先在 unit 目录写 `worktree-override.md`（reason / scope / approval）。 - -ff-note 落盘、收尾提交前运行 commit gate： - -```bash -python3 .codestable/tools/codestable-worktree-gate.py --root . --json commit --unit .codestable/features/YYYY-MM-DD-{slug} -``` - -gate 不通过就先处理 findings，不把"验证已过"当成完成。gate 工具的安装与 branch-guard hook 说明见 `.codestable/reference/branch-guard-hooks.md`。 - ---- - -## 写代码时守住这几条 - -design / implement 的硬约束在 fastforward 的精简版。没 design doc 不代表可以不讲——这些是让你"直接动手"时不偏向 AI 默认会踩的坑。 - -先做 `.codestable/reference/shared-conventions.md` 第 7 节的**第一性原则 pre-pass**：外部行为、不可破约束、最小充分改动、必须不写的东西。下面每条都用这四项压住发散。 - -### 先想"放在哪儿"再写 - -30 秒回答：**这次要加的东西在项目结构里属于哪儿？** - -- 现有模块本该承担？→ 在那扩展，别另起 -- 横跨多个模块？→ 抽公共层 / 让某一方主导 -- 已有模块叫法不同？→ grep 同义词 -- 跟现有都不像？→ 多半该切回完整 design 流程 - -默认坑：**不思考就往眼前最顺手的文件里加**——加完就成"什么都装的筐"。 - -### 扫一眼要改的文件现在什么状况 - -开写前看一眼：文件多长？承担几件事？类有多少方法？新加的是自然扩展还是把它推向"什么都能干"？ - -健康就直接加；要先收拾（拆长文件 / 抽重函数）就**先收拾再加**，范围锁死为"只搬不改行为"；结构性问题（职责重划 / 模块拆合）→ 停下来回 design 流程。 - -### 默认写最少的代码 - -只写用户明确要的。不顺手加： - -- "以后可能要"的配置项 / 参数开关 / 抽象层 / 接口 / 工厂 -- 没人要的防御性兜底 / try-catch -- 用户没提的边界处理 - -判据：写完觉得"是不是还得加点 X"——X 是不是用户能感知到的？不是就别加。多出来的代码不是中性的，是后人维护的负担。 - -### 只动该动的 - -只改要改的函数。同文件里别的函数丑 / 命名怪——**除非和这次冲突，否则别碰**。新代码风格匹配当前文件已有写法。看到值得改的别处 → "顺手发现：{文件:行号} {问题}，不在本次范围"让用户决定。 - -### 新逻辑默认放新文件 - -会被其他地方引用 → 新文件；只一处用的小工具函数 → 就近放。 - -### 不打补丁分支 - -冒出 `if (特殊情况) { 特殊处理 }` → **停**。这种分支基本只因为思路没覆盖到这种情况，硬写下去得到的是"为让代码能跑而加的特殊逻辑"。要么改数据结构让它不需要特殊处理，要么明确承认是边界情况并注释说明为什么特殊。 - -### 反射信号触发就停 - -- 往 > 300 行文件追加 / 往 > 10 个方法的类加方法 -- 函数做的事越来越多超过一屏 -- 写第二段"跟上面那段基本一样改了两个变量"的代码 -- 函数参数加到第 4 个 -- 往 `utils.ts` / `helpers.ts` 万能 util 堆东西 -- 新起概念名时先 grep 同名 / 近义命名 - -完整清单看 `.codestable/reference/shared-conventions.md` 第 7 节。 - ---- - -## 写完回写 `{slug}-ff-note.md` - -代码写完、验证完、用户确认效果 OK **之后**才动这一步——动手前先建空壳会破坏 ff 的轻体感。 - -### 自动生成 slug - -不问用户。规则： - -- 从用户最初的请求里抽 2-4 个英文 kebab-case 词概括动作 / 对象（如 "rename-cwd-helper"、"add-export-button"、"fix-toolbar-layout"） -- 不抽业务名词缩写、不音译中文、保持小写连字符 -- 拿不准就保守一点："tweak-{对象}" / "small-{动作}" 也比强求精准好 - -最终路径：`.codestable/features/YYYY-MM-DD-{slug}/{slug}-ff-note.md`，日期用今天。 - -### 模板 - -```markdown ---- -doc_type: feature-ff-note -feature: {slug} -date: YYYY-MM-DD -requirement: {req-slug 或留空} -tags: [...] ---- - -## 做了什么 -{1-3 句：解决什么需求 / 加了什么能力，业务视角} - -## 改了哪些 -- {file:行号区间或函数名} — {一句话说改了什么} -- ... - -## 怎么验证的 -{1-2 句：跑了哪些验证 / 浏览器走通了哪条路径 / 跑了什么测试} - -## 顺手发现（可选，不阻塞） -- {文件:行号} {问题简述} — 不在本次范围 -``` - -**写得真的轻**：每节就那么几行，不要把它写成迷你 design / 迷你 acceptance。这份文档的目标是"半年后有人看 git log 能跳进来 30 秒搞清楚做了啥"，不是替代标准流程。 - -落盘后告诉用户："已写 `{slug}-ff-note.md`，本次 fastforward 闭环。" - ---- - -## 不做什么 - -- **不写 design doc / checklist / acceptance**——这就是 fastforward 的意义。要写就去 `cs-feat-design` -- **不跟用户确认方案**——用户让你做小功能就是不想等你开会 -- **不在 `.codestable/` 里留 `{slug}-ff-note.md` 之外的新文件**——除非发现值得沉淀的坑 / 技巧，另起对话用 `cs-keep` 写 - ---- - -## 什么时候跳出 fastforward - -干到一半发现下面任一情况，**停下来告诉用户"这比想象的复杂，建议切回完整流程"**： - -- 改动涉及 3 个以上子系统 -- 需要引入新术语或和现有术语冲突 -- 要打破 `.codestable/requirements/adrs/` 既定的模块边界 ADR -- 用户追加的要求让范围翻倍 - -切回方式：触发 `cs-feat-design`。已写的代码在 design 里标"已部分实现"即可。 - ---- - -## 退出条件 - -- [ ] 代码写完且用户确认效果 OK -- [ ] `{slug}-ff-note.md` 已落盘且四节填齐（顺手发现可省） -- [ ] 没有未对齐的"顺手发现"（都进 ff-note 末节，留给后续） - ---- - -## 收尾提交 - -按 `.codestable/reference/shared-conventions.md` 第 4 节"scoped-commit"规则执行。本通道： - -- **提交范围**：本次代码改动 + `{slug}-ff-note.md` -- ff-note 落盘后告诉用户"已就绪，是否代为 commit？"，用户明确同意才执行 - -收尾 commit 前先进入 `cs-code-review` 做一轮独立 diff 评审，Critical / Important 未清零不进 commit；scoped-commit 发起权归 `cs-code-review`。 - -按 `shared-conventions.md` 第 3 节"feature-ff"收尾推荐顺序逐项一句话提示（用户"不用"立即跳过）： - -1. 暴露的坑或拍板的长期约束 → "沉淀到 compound？（`cs-keep`）" -2. 最后问是否代为 scoped-commit - ---- - -## 容易踩的坑 - -- 完全跳过知识检索就写——这个技能的唯一理由就是让你搜一下再写 -- 把搜到的 learning / decision 当"参考"而不是"约束"——decision 拍过板，违反要么重新 decision 要么别做 -- 开始写 design doc——fastforward 就是不写 design -- 发现任务变复杂还硬在 fastforward 推——切回成本远低于带着错误方案改到底 -- **动手前就建 ff-note 空壳**——破坏 fastforward 的轻体感，必须代码 + 验证完才回写 -- **把 ff-note 写成迷你 design / 迷你 acceptance**——四节加一起十几行就够，多了说明这事不该走 fastforward -- **跳过 ff-note 直接 commit**——和 issue-ff 强制 fix-note 同样的理由：没记录后人追溯不了 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-feat` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-feat-impl/SKILL.md b/plugins/codestable/skills/cs-feat-impl/SKILL.md index 69bc7c8..d69988c 100644 --- a/plugins/codestable/skills/cs-feat-impl/SKILL.md +++ b/plugins/codestable/skills/cs-feat-impl/SKILL.md @@ -1,296 +1,23 @@ --- name: cs-feat-impl -description: Feature 实现。触发：approved design/checklist 后开工，或修 review/QA blocking。 +description: Feature implementation 兼容入口。旧调用保留；执行时转入 cs-feat 主流程的 implementation 阶段。 --- # cs-feat-impl -## 启动必读 +本技能是 `cs-feat` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_stage: implementation` -到这一步用户已经在方案上签过字了，你的活是把方案变成代码。容易出问题的不是写代码本身，而是**实现路上发现方案没覆盖到的情况时怎么办**——硬冲下去就把方案当摆设了。下面整套规则就是为了让"停下来"成为默认动作。 +## 执行规则 -**执行原则**：实现不是"一口气改完再说"，而是按已批准 checklist 做可验证增量。每一步要先明确退出信号，做完立刻拿证据验证；失败先诊断和重试，仍失败再写窄范围修复说明；连续失败才交还用户。不要让未验证的中间状态滚进下一步。 +1. 按已安装 skill 名称加载 `cs-feat` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-feat` 主协议继续执行，并带上入口意图 `requested_stage: implementation`。 +3. 不要要求用户重新调用 `cs-feat`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -**推进原则**：实现阶段要让任务随时可恢复、可归因、可审计。开始前先确认基线；每步完成就更新 checklist 和证据；失败只修当前失败标准；每步都检查清洁度；遇到用户中断就在 step 边界停；学到会影响后续 feature 的知识先记录为候选，交给 acceptance 收尾沉淀。 +## 维护规则 -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md` 第 0 节。 - ---- - -## 执行 gate（worktree + commit） - -进入实现前运行 start gate，路径用项目运行时 `.codestable/tools/...`： - -```bash -python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/features/YYYY-MM-DD-{slug} -``` - -gate 不通过就不要开始改代码；用户批准 override 时先在 unit 目录写 `worktree-override.md`（reason / scope / approval）。 - -dogfood / 临时隔离仓库例外：只有当用户任务明确要求在一次性隔离 repo 里真实执行 workflow，且该 repo 不是交付目标主仓库时，允许不创建 linked worktree；仍必须在 unit 目录写 `worktree-override.md`，记录 `reason=dogfood-ephemeral-repo`、用户授权原文、影响范围和后续清理策略。不能把这个例外用于普通 feature 实现。 - -实现完成、输出汇报前运行 commit gate： - -```bash -python3 .codestable/tools/codestable-worktree-gate.py --root . --json commit --unit .codestable/features/YYYY-MM-DD-{slug} -``` - -gate 不通过就先处理 findings，不把"测试已过"当成完成。gate 工具的安装与 branch-guard hook 说明见 `.codestable/reference/branch-guard-hooks.md`。 - ---- - -## 写代码时的三条姿态 - -先做 `.codestable/reference/shared-conventions.md` 第 7 节的**第一性原则 pre-pass**：明确外部行为、不可破约束、最小充分改动和必须不写的东西。具体规则是这三条姿态的落点，理解姿态比记规则重要。 - -### 1. 默认写最少的代码 - -只写当前步骤明确要的东西。不顺手加"以后可能要"的可配置项、抽象层、参数开关、防御性兜底。判据：写完一段觉得"是不是还得加点 X"，先问 X 是不是当前用户能感知到的——不是就别加。整体写完一看 200 行其实 50 行能讲清楚 → 重写。多出来的代码不是中性的，是后人维护的负担。 - -### 2. 只动该动的，不顺手"改善"邻居 - -改某个函数时只改那个函数。同文件里别的函数风格丑、命名怪——除非和本次改动直接冲突，否则别碰。新代码风格匹配当前文件已有写法。混进的"顺手改"会把功能 PR 稀释成"一坨综合改动"，review 成本翻几倍。值得改的按下文"顺手发现"格式记成后续 issue。 - -孤儿处理：你这次改动让某个 import / 函数变成死代码 → 删掉。**不是**你改动造成的死代码 → 留着记成顺手发现。 - -### 3. design 没说的事别自己拍板 - -写到一半发现 design 没覆盖的角落（边界条件、错误路径、方案外文件）——默认停下来回 design 谈。下面"补丁分支"和"术语守护"是这条姿态的两个典型落点；**任何"design 没明说我替它选了一个"的瞬间都触发**。 - ---- - -## 启动检查 - -### 1. 方案文件够不够撑实现 - -frontmatter：`doc_type=feature-design` / `feature` 一致 / `status=approved` / `summary` 非空 / `tags` ≥ 2。 - -**标准 design**（节 0/1/2/3/4）： -- 第 0 节有内容；第 1 节含"明确不做"和复杂度档位 -- 第 2.1 名词层用"现状 → 变化"两段式，每个新增/变更接口至少一个示例 + 来源位置 -- 第 2.2 编排层开头有主流程图，"现状 → 变化"齐全，流程级约束已记 -- 第 2.3 挂载点按"删了它 feature 是否消失"判据，没把内部代码改动误列进来 -- 第 3 节有关键场景清单 + 反向核对项（不含测试代码 / framework 选型） - -**Fastforward design**（节 0/1/2/3）： -- 第 0 含"明确不做"；第 1 有改动点（文件 + 函数/类型名） -- 第 2 验收标准每条可验证；第 3 推进步骤有退出信号 - -任一项不达标 → 退回 `cs-feat-design` 补齐。原因：方案漏的项实现时一定要现场补，等于绕过 checkpoint。 - -**注意**：标准 design 第 3 节"验收契约"只说"做完后什么应该成立"，不说"具体怎么做"。改动文件清单 / 函数级落点 / 测试代码归 implement 自决，不要因为 design 里没写就退回去要求补。 - -### 2. {slug}-checklist.yaml 在不在 - -- 文件存在，`feature` 字段一致 -- `steps` 非空（design 已产出，paradigm 维度切片，4-8 步）；`checks` 非空 -- 不存在 → 退回 `cs-feat-design` 生成 - -### 3. 把上下文读全 - -- 方案 doc 全文（标准 design 重点：第 1 节、2.1/2.2/2.3/2.4、3） -- `{slug}-checklist.yaml`、需求来源（用户描述 + brainstorm note）、`.codestable/attention.md` -- 第 2.1 节接口示例的来源位置 / fastforward 第 1 节改动点提到的代码文件——读相关函数即可 -- 如果是 review-fix：读取 `{slug}-review.md`，只把 unresolved `blocking` findings 作为本轮目标 -- 如果是 qa-fix：读取 `{slug}-qa.md`，只把 failed / blocked QA items 作为本轮目标 - -### 4. 跟用户确认从哪一步开始 - -通常第 1 步；接续上次中断从已 `done` 的下一步继续。 - -design 给的 `steps` 是 paradigm 维度切片（编排骨架 → 计算节点 → 持久化 → 测试），**具体每步改哪个文件由你执行时决定**。如果某一步实际是 3 个独立子动作、或发现微重构是它的前置（参考反射检查），跟用户对齐后追加 / 拆分 steps，**不偷偷做**。 - -### 5. 基线预检 - -动第一行代码前，读取 design 里的"必跑验证命令 / 基线风险"。对本 feature 最相关、成本可接受的命令先跑一遍（至少 typecheck / targeted tests；前端可先确认 dev server / 页面入口可打开）。 - -- 全绿：在工作记录里记"基线预检通过：{命令列表}" -- 有红灯：先判断是既有问题还是本 feature 必须先修的前置 - - 既有红灯且不影响当前 feature：记录为基线风险，后续验证只要求"不新增失败 / targeted checks 通过"，最终汇报必须写清 - - 既有红灯但会影响当前 feature：停下来和用户确认，是先补 safety net / 修基线，还是调整 design - - 无法归因：不要继续大改，先缩小命令或读错误定位 - -这一步的目的不是把全仓库修绿，而是避免把"启动前已经坏"误判为本 step 失败，也避免在坏基线上继续堆代码。 - -**design 第 2.5 节微重构的衔接**： - -- 如果 2.5 结论是"做微重构（拆文件）"或"做微重构（重组目录）"，checklist 第 1 步就是它——**独立跑完**，按 2.5 节"行为不变怎么验证"那条核对： - - 拆文件：编译绿灯 + 现有测试通过 + 对外接口签名零 diff - - 重组目录：编译绿灯 + 现有测试通过 + diff 仅限文件移动 + import 路径更新（**没有任何函数体改动**） - - **不要合并到下一步**——一旦混在一起，行为变更和结构变更就分不开，出问题回滚不到干净中间态 -- 如果 2.5 结论是"不做"但写到中途反射检查触发了拆分信号 → 走下面"反射检查"那条路径（停下来 → 和用户对齐 → 能 provable 解决就追加独立 step），**不要绕过用户确认偷偷追加** -- 如果 2.5 末尾有"建议沉淀的 convention"段：implement 阶段**不主动归档**——只在重组目录跑通且行为零改动确认后，在汇报里带一句"design 2.5 建议沉淀的 convention 已就绪，等 acceptance 阶段确认是否走 cs-keep"，把决定权交给 acceptance / 用户 - ---- - -## 实现期间的几条核心约束 - -### 严格按 steps 顺序走 - -按 `steps` 列表顺序执行，不合并、不跳。每一步开始前先重读该 step 的 `action` / `exit_signal`，确认它是本轮唯一目标；每完成一步立即验证退出信号，并把 status `pending` → `done`。 - -最常见违规是"顺手把下一步也做了"——每步都对应独立可验证的退出信号，两步合做意味着出问题时不知道是哪一步引入的、回滚也回不到干净中间态。 - -每步完成后立刻把 `{slug}-checklist.yaml` 对应 step 状态落盘。不要等所有步骤完成再统一改；状态文件就是断点恢复锚点。中断恢复时先读它，而不是靠记忆。 - -### 每步都要有证据块 - -完成每个 step 后，在工作记录 / 汇报素材里留下最小证据： - -- 退出信号：原文摘出 -- 验证动作：跑了什么命令 / 看了什么页面 / 检查了什么 diff / 调了什么接口 -- 结果：通过 / 未通过；失败写真实错误摘要 -- 影响面：本步新增 / 修改的主要函数、类型、路由、配置或文档 -- 清洁度：本步新增代码里是否有调试输出、临时 TODO/FIXME、注释掉代码、无用 import、方案外文件 - -证据不要求每步都发给用户，但最终完成汇报必须能按 step 追溯。UI step 的证据不能只写 typecheck，必须有浏览器 / 截图 / 肉眼验证；后端接口 step 优先用测试或真实请求证明；纯类型约束可以用 typecheck 证明。 - -### Step 清洁度检查 - -每步验证时额外看本步 diff： - -- 新增调试输出：`console.log` / `console.error` / `print` / `fmt.Println` / 临时 logger -- 新增临时 TODO / FIXME / XXX -- 注释掉的旧代码或大段死代码 -- 新增 import 但未使用 -- 非本 step 需要的文件改动 - -命中就按失败处理：能当场删掉就删并重跑验证；确实是功能的一部分（例如新增日志能力）必须在 design / 汇报里说明原因和范围。清洁度不是审美问题，它是防止临时施工痕迹进入后续阶段。 - -### 不做方案外的改动 - -发现值得重构的点（参考 `.codestable/reference/shared-conventions.md` 第 7 节"写代码时的反射检查"），只要**不在本次功能影响面内**就记成后续 issue： - -```markdown -> 顺手发现：{文件:行号} {问题简述}。不在本次范围，记录待后续 issue。 -``` - -顺手改的代码不在方案里，验收对不上；后人 git blame 也分不清是为本次功能还是顺手。 - -### 术语守护 - -**标准 design**：新写的类型 / 函数 / 变量名都要去方案 doc 第 0 节对照，不允许出现 doc 里没有的新概念。要引入新概念 → 先停下来改第 0 节、grep 防冲突、用户确认。 - -**Fastforward design**：没有正式术语表，但要新起概念名时也要 grep 一下当前代码防冲突。 - -代价：术语冲突意味着同概念两个名字 / 同名字两个概念——后者会让搜索完全失效。 - -### 出现"补丁分支"的冲动时停下来 - -写代码时冒出 `if (特殊情况) { 特殊处理 }` 这种结构，**停**。这种分支基本只有一个原因：方案没覆盖到这种情况。继续写得到的是"为了让代码能跑而加的特殊逻辑"——下次别人改这块时不知道这个分支为什么存在。回方案谈：补进 design / 砍掉 / 明确为遗留问题。 - -### Step 失败恢复：诊断 → 窄修复 → 交还 - -某个 step 的退出信号或相关测试失败时，不直接推进下一步，也不把失败掩进最终汇报。按三段处理： - -1. **第一次失败：失败诊断** - 写清失败项、实际错误、刚改过的范围、根因假设；只围绕当前 step 做一次重试。重试前不要扩大 scope。 -2. **第二次失败：窄范围修复说明** - 如果重试仍失败，在 feature 目录写一份临时 `{slug}-step-N-fix.md`（或在完成汇报中等价记录）： - - 失败的 exit_signal / checks - - 根因判断 - - 只允许改哪些文件 / 行为 - - 修复后必须重跑哪些验证 - 执行这份窄修复，成功后回到原 step 的验证，不直接标 done。 -3. **第三次失败：交还用户** - 仍失败就停下来，报告三次尝试、证据、当前风险和建议下一步。不要为了"完成流程"继续改大范围代码。 - -这个机制只处理当前 step 的失败，不是绕过 design 的许可证。发现设计缺口仍然回 `cs-feat-design`，不是用窄范围修复说明现场拍板。 - -### 用户中断与续跑 - -如果用户在实现中途发来新消息： - -- 当前 step 未到安全点：先把正在做的最小变更验证 / 回滚到可解释状态，再回应 -- 当前 step 已验证：更新 checklist 状态和证据后停在下一步开始前 -- 用户要求改方向：不要继续执行旧 checklist；先判断是改 design、拆 step、还是取消当前 feature - -恢复时固定顺序：读 design → 读 checklist 当前状态 → 读最近实现汇报 / 临时 step fix 文档 → 从第一条 `pending` step 继续。 - -### 代码质量反射检查 - -除上面流程约束外，还有一组针对代码质量的反射检查——看 `.codestable/reference/shared-conventions.md` 第 7 节。 - -核心：**不是"超过 N 行必须拆"，而是"遇到 X 情况就停下来问自己"**。每条对应 AI 默认会走进去的坑（往大文件继续追加、往大类加方法、补丁分支、复制粘贴、第 4+ 个参数、往万能 util 堆东西）。 - -反射检查结论是"要拆 / 新建文件 / 重命名 / 抽共用层"且超出现有 steps 范围 → 跟用户商量决定，不偷偷拆完继续写。判据按和 design 2.5 一致的边界分两路（避免 impl 自己造一套口径）： - -- **能用"只搬不改行为"解决**（拆函数 / 拆文件 / 移动定义，编译器全程绿灯，对外签名零 diff）→ 和用户对齐后**追加为独立 step**插在当前 step 之前，跑完独立验证退出再继续 -- **超出"只搬不改行为"边界**（要改函数签名 / 改返回值结构 / 改调用关系语义 / 模块拆合）→ **本 feature 不做**，记成"顺手发现"格式提示用户后续走 `cs-refactor`，当前 step 用最少的改动绕过去；不要因为"反正都看到了"就在 feature 里顺手做掉——这会把功能 PR 稀释成综合改动，也违反 design 2.5 早就划好的边界 - -### 最后一轮本地审计 - -所有 steps 标 `done` 后，完成汇报前做一轮小型 final audit： - -1. 重读 `{slug}-design.md` 第 1 / 2 / 3 节和 `{slug}-checklist.yaml` -2. 逐条确认 steps 全 done、checks 还未验收但已有实现证据 -3. 重新跑本 feature 所需的 build / typecheck / lint / test 或项目等价命令；有前端改动则跑浏览器验证 -4. 过一遍 `git diff`，检查本次新增的 debug 输出、临时 TODO/FIXME、注释掉的代码、无用 import、方案外文件 -5. 用第 3 节关键场景倒查：有没有某条没有证据；没有就补测或回实现 -6. 列出实际交付物：新增 / 修改 / 删除的代码入口、配置、schema、路由、文档、roadmap 状态，为 acceptance 的交付物复核做索引 -7. 列出知识候选：项目命令、环境坑、稳定 convention、库 API 坑、用户确认的偏好；不直接写入 knowledge，只交给 acceptance 第 8 节处理 - -audit 发现问题就回到对应 step 处理，不把问题留给 acceptance 首次发现。 - -### review-fix 模式 - -当 `cs-code-review` 产出 `status: changes-requested` 且有 unresolved `blocking` findings 时，进入 review-fix 模式： - -1. 只读取并修复 review 报告里的 blocking findings；不要借机实现新需求、重构邻居或处理非阻塞建议。 -2. 每个 REV 编号都要留下修复证据：改动文件、验证命令、为什么阻塞已解除。 -3. 如果修 blocking 需要改变 design 契约、扩大 feature 范围或触碰 roadmap item 边界，停下来回 `cs-feat-design` / 用户确认。 -4. 修完后跑相关验证和清洁度检查，输出 review-fix 汇报。 -5. 下一步必须重跑 `cs-code-review`；不能直接进入 `cs-feat-accept`。 - -review-fix 不要求 checklist 新增普通 step，除非用户明确要求把修复动作纳入 checklist 追踪。默认把 REV 编号和证据写在汇报里，保留 review 报告作审查输入。 - -### qa-fix 模式 - -当 `cs-feat-qa` 产出 `status: failed` 或 `status: blocked` 且失败项归因于本 feature 时，进入 qa-fix 模式： - -1. 只读取并修复 QA 报告里的 failed / blocked items；不要借机处理新需求、非阻塞建议或 review 已接受的 residual risk。 -2. 每个 QA 编号都要留下修复证据：改动文件、验证命令、为什么失败已解除。 -3. 如果修 QA 失败项需要改变 design 契约、扩大 feature 范围或触碰 roadmap item 边界，停下来回 `cs-feat-design` / 用户确认。 -4. 修完后跑相关验证和清洁度检查，输出 qa-fix 汇报。 -5. qa-fix 改变了代码 diff，下一步必须重跑 `cs-code-review`；review passed 后再重跑 `cs-feat-qa`。不能直接进入 `cs-feat-accept`。 - -qa-fix 不要求 checklist 新增普通 step，除非用户明确要求把修复动作纳入 checklist 追踪。默认把 QA 编号和证据写在汇报里，保留 QA 报告作复测输入。 - ---- - -## 写完后输出统一汇报 - -所有步骤完成后，按 `references/reference.md` 的"实现完成汇报"模板输出并停等用户 review。模板必须列出真实 `git status`、按步骤归类的改动、方案外触碰、新概念、step 证据、清洁度、交付物、知识候选、最后一轮本地审计和验收场景自检。 - ---- - -## 测试用例怎么落 - -标准 design 第 3 节"关键场景清单"每条 = 一个可验证行为约束。把每条变成可观察证据：单测 / 集成 / 手工操作 / 类型编译期保证。coding step 适合自动化测试时，可在 step 内采用 TDD vertical slice；这是 `cs-feat-impl` 的内嵌实现策略，不是切换到独立 `tdd` skill。具体测试策略看 `references/reference.md` 和 `references/tdd.md`。 - ---- - -## 退出条件 - -完整 checklist 见 `references/reference.md`。主文件保留硬门摘要： - -- [ ] 所有 steps 的 status 都 `done`，且每步有退出信号证据。 -- [ ] 完成汇报已输出，用户 review 通过（或 review-fix / qa-fix 汇报已输出，等待重跑对应 gate）。 -- [ ] 没有未处理的"需要叫停"信号、方案外改动或清洁度缺口。 -- [ ] 开始前做过基线预检；完成前做过最后一轮本地审计。 -- [ ] 第 3 节关键场景每条都有证据 / 测试覆盖（fastforward 对照第 2 节）。 - ---- - -## 退出后 - -告诉用户下一步：普通实现完成后触发 `cs-code-review`；review-fix 后重跑 `cs-code-review`；qa-fix 后重跑 `cs-code-review` 和 `cs-feat-qa`。不要顺手进入验收报告；完整话术见 `references/reference.md`。 - ---- - -## 容易踩的坑 - -完整列表见 `references/reference.md`。最常见红线：半成品汇报、方案外顺手改、新概念不回填、补丁分支硬冲、跳过 review/QA gate、关键场景没有证据。 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-feat` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-feat-qa/SKILL.md b/plugins/codestable/skills/cs-feat-qa/SKILL.md index 9a9648e..6d0cdac 100644 --- a/plugins/codestable/skills/cs-feat-qa/SKILL.md +++ b/plugins/codestable/skills/cs-feat-qa/SKILL.md @@ -1,267 +1,23 @@ --- name: cs-feat-qa -description: Feature QA gate。触发：code review passed 后跑验证，或用户要求 QA。 +description: Feature QA 兼容入口。旧调用保留；执行时转入 cs-feat 主流程的 QA 阶段。 --- # cs-feat-qa -## 启动必读 +本技能是 `cs-feat` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_stage: qa` -本阶段是 review 通过后、acceptance 前的 QA gate。它只读代码和产物、运行验证命令 / 浏览器 / API / 手工检查，并写 `{slug}-qa.md`。默认不改代码、不改 checklist、不改 design；发现失败后回到 `cs-feat-impl` 的 qa-fix。 +## 执行规则 -QA 的目标不是再做一遍 code review，也不是最终归档验收报告。它回答一个问题：在当前工作区里，design 承诺的关键行为是否有足够的运行证据，review 指出的测试焦点和 residual risk 是否被实际覆盖。 +1. 按已安装 skill 名称加载 `cs-feat` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-feat` 主协议继续执行，并带上入口意图 `requested_stage: qa`。 +3. 不要要求用户重新调用 `cs-feat`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md` 第 0 节。 +## 维护规则 ---- - -## 独立 QA Task agent（可选） - -QA 可以按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则，启用独立 runner 来执行浏览器、API、CLI、集成测试或环境复核，尤其是高风险功能、外部集成、真实浏览器路径和 goal 模式中的核心验收路径。但它是辅助执行者，不是 QA owner： - -- 主 agent 负责建立 Verification Matrix、决定哪些证据阻塞、核验 runner 输出，并写 `{slug}-qa.md` 的最终 verdict。 -- runner 默认只读代码和产物，只运行验证；如需改测试或配置，必须退回 `cs-feat-impl` qa-fix。 -- runner 输出必须被写入 QA 报告的证据来源；未经主 agent 本地核验的结论只能作为 `residual-risk` 或待复核项。 -- 普通低风险非功能性 feature 不强制独立 runner，避免把 QA 成本固定放大。 - ---- - -## 输入 - -进入 QA 前必须读取： - -- `.codestable/attention.md` -- `{slug}-design.md` -- `{slug}-checklist.yaml` -- `{slug}-review.md` -- goal / gate 模式下的 `{slug}-evidence-pack.md`、`{slug}-gate-results.json`、`{slug}-dod-results.json` -- 实现完成汇报 / review-fix 汇报（如有） -- `git status --short` -- `git diff`（有 staged diff 时也读 `git diff --cached`） -- design 里的必跑验证命令 / 基线风险 / 验收场景 / 证据类型 / 清洁度规则 -- review 报告第 4 节 Test And QA Focus 和第 5 节 Residual Risk -- 项目测试入口：README、package scripts、Makefile、CI 配置、历史 acceptance / qa 报告里与本 feature 相关的命令 -- feature 性质判断：功能性 / 非功能性，以及哪些场景是核心验收路径 - -如果工作区有 feature 外的既有 dirty 文件，记录 baseline/无关变更；QA 结论只覆盖本 feature 可归因的改动。无法区分归因时写 `blocked` 或 `residual-risk`，不要假装通过。 - ---- - -## Feature 性质与证据硬门 - -QA 先判定 feature 性质，再决定必须拿到什么证据。这个判定写进 QA 报告，acceptance 会复核。 - -### 功能性 feature - -满足任一条件就按功能性处理： - -- 改变用户可见行为、UI、API、CLI、后台任务、权限、持久化、集成、运行时路由或错误语义。 -- roadmap / design 的成功标准里出现“用户能...”“系统会...”“真实请求 / turn / smoke / e2e / browser / API”等运行行为。 -- review 把某条验证标成必须覆盖，且它对应实际运行路径。 - -功能性 feature 的核心路径不能降级成 residual-risk： - -- design 第 3 节关键场景、checklist `checks`、roadmap success criterion、review Test And QA Focus 中属于核心功能路径的项，必须有实际运行证据：unit / integration / e2e / browser / API / CLI / manual smoke 任选合适组合，但证据必须能观察到行为。 -- 只跑 typecheck / lint / diff review，不能证明核心功能路径通过。 -- 外部凭证、服务、设备、网络或成本导致核心路径无法运行时，结论是 `blocked`；如果实现明显缺测试或行为失败，结论是 `failed`。 -- 只有 design 在实现前已明确把某条路径定义为“条件性非阻塞”（例如 CI 无 auth 时只验证 unavailable path），且 QA 已验证替代路径和 skip reason，才允许把这条写成 residual-risk。QA 现场不能临时把原本的核心验收路径改成非阻塞。 - -### 非功能性 feature - -以下类型默认按非功能性处理，除非它同时改变运行行为： - -- 文档、architecture / roadmap / requirement / learning 回写。 -- 纯重构、命名整理、目录迁移、死代码清理，且声明行为不变。 -- 测试补强、类型补强、lint/build 配置、脚本整理、生成物同步。 -- 内部设计文档、协议说明、agent skill 文案更新。 - -非功能性 feature 不强制 e2e / browser / API / 手工真实链路；它可以用静态检查、diff 复核、文档一致性、类型检查、构建、目标测试、快照或 schema 校验通过。QA 报告必须写明“不需要端到端运行验证”的理由，以及本 feature 实际采用的替代证据。 - -如果非功能性 feature 触碰了生产路由、用户可见文案、权限、安全边界、数据迁移或外部集成，即使目标是“重构/整理”，相关触碰点仍按功能性核心路径验证。 - -## 启动检查 - -1. `{slug}-design.md` 存在且 `status=approved`。 -2. `{slug}-checklist.yaml` 存在，`steps` 全 `done`，`checks` 仍未由 acceptance 全部通过。 -3. `{slug}-review.md` 存在，frontmatter `doc_type=feature-review`、`status=passed`，无 unresolved `blocking` findings。 -4. goal / gate 模式下，evidence pack、gate results、DoD results 必须存在；gate warnings 和 Residual Risks 纳入 QA matrix。 -5. 如果 review 报告不是基于当前 diff：先回 `cs-code-review` 复审。qa-fix 或其他代码改动会让旧 review 过期。 -6. 如果已有 `{slug}-qa.md`： - - `status=passed` 且 diff 未变化：提示可进入 `cs-feat-accept`。 - - `status=failed` / `blocked`：读取旧失败项，确认是否处于 qa-fix 后的复测。 - - diff 已变化：重新 QA，并在报告里记录轮次。 - ---- - -## QA 流程 - -### 1. 建验证矩阵 - -从 design 第 3 节关键场景、design 必跑命令、review Test And QA Focus、review residual risk、evidence pack 的 Validation Commands / DoD Results / Residual Risks 汇总 QA 矩阵： - -- Feature type：functional / non-functional / mixed。 -- 核心性：core-functional / supporting / non-functional。 -- 场景：输入 / 触发 → 期望可观察结果。 -- 证据类型：unit / function / integration / e2e / browser / API / manual / typecheck / diff。 -- 命令或动作：具体命令、页面路径、API 请求、手工步骤。 -- 失败判据：什么结果算 fail，不写"看起来正常"。 -- 归因：本 feature / 既有基线 / 环境不可用 / 无法判断。 - -优先使用项目已有测试入口和既有工具，不为了 QA 临时引入新测试框架。需要新增测试代码时，QA 不直接写；把它记为 failed item，回 `cs-feat-impl` qa-fix。 - -### 2. 运行验证 - -按从便宜到昂贵、从自动到手工的顺序运行： - -1. 基线相关命令：typecheck / lint / build / targeted unit 或项目等价命令。 -2. 与 feature 直接相关的 unit / function / integration / e2e 测试。 -3. review 与 evidence pack 指出的重点验证、gate warnings 和 residual risk。 -4. 功能性前端 / 用户可见改动：浏览器验证、截图或明确手工路径；只跑 typecheck 不算 QA 通过。 -5. 功能性 API / 后端 / 运行时能力：真实请求、集成测试或可复现的命令行调用。 -6. 非功能性改动：静态检查、diff 复核、文档一致性、schema/快照/类型/构建/目标测试，并记录为什么无需端到端运行。 -7. 清洁度复核：debug 输出、临时 TODO/FIXME、注释掉代码、无用 import、方案外文件。 - -每条证据必须记录命令、退出码或观察结果。命令不可运行时写具体原因：缺依赖、服务不可启动、外部凭证缺失、环境限制、成本过高。不可运行不是自动通过。 - -### 3. 判定 - -- `passed`：所有 blocking QA items 通过；功能性核心路径都有运行证据；非功能性 feature 有充分替代证据和“不需要端到端运行”的理由；不可运行项只剩非核心 residual risk。 -- `failed`：关键场景失败、必跑命令失败且归因本 feature、review 重点未覆盖、测试缺口会影响验收可信度、功能性前端未做浏览器验证、功能性 API / 运行时路径没有实际调用证据。 -- `blocked`：输入缺失、review 未通过、环境不可用到无法判断核心行为、dirty diff 归因不清。 - -QA failed 时不要直接修代码。输出报告后进入 `cs-feat-impl` qa-fix；qa-fix 修完必须先重跑 `cs-code-review`，再重跑 `cs-feat-qa`。 - -`residual-risk` 只能承载非核心风险、明确延期项或非功能性无法完全复核的边界。它不能承载“核心功能路径没跑过”“真实用户路径没验证”“必跑命令没执行”这类验收缺口。 - ---- - -## 报告模板 - -报告路径：`.codestable/features/{feature}/{slug}-qa.md`。 - -```markdown ---- -doc_type: feature-qa -feature: YYYY-MM-DD-slug -status: passed|failed|blocked -tested: YYYY-MM-DD -round: 1 ---- - -# {slug} QA 报告 - -## 1. Scope And Inputs - -- Design: {path} -- Checklist: {path} -- Review: {path} -- Evidence pack: {path / none} -- Gate results: {path / none} -- DoD results: {path / none} -- Diff basis: {git status / git diff 摘要} -- Baseline dirty files: {none / 列表 + 归因} -- Feature type: functional|non-functional|mixed -- Core evidence gate: {功能性核心路径列表；非功能性写不需要端到端运行的理由} - -## 2. Verification Matrix - -| ID | 来源 | 核心性 | 场景 / 风险 | 证据类型 | 命令或动作 | 期望 | 结果 | -|---|---|---|---|---|---|---|---| -| QA-001 | design S1 | core-functional/supporting/non-functional | {描述} | unit/integration/e2e/browser/API/manual/typecheck/diff | `{命令}` | {期望} | pass/fail/blocked | - -## 3. Command Results - -- `{命令}` → exit {code}：{摘要} -- 未运行：{命令} → {具体原因 + 是否阻塞} - -## 4. Scenario Results - -- [ ] QA-001 {场景}：pass/fail/blocked - - Evidence: {输出 / 截图 / 请求响应 / 手工路径} - - Notes: {归因 / 风险} - -## 5. Findings - -### failed - -- [ ] QA-001 {失败项} - - Evidence: {证据} - - Impact: {为什么影响验收} - - Expected fix scope: {只描述失败边界，不替实现写方案} - -### blocked - -- [ ] QA-00N {阻塞项} - -### residual-risk - -- {无法完全验证但不阻塞的风险；没有写 none} -- 不允许出现：功能性核心路径未运行、真实用户/API/运行时路径未验证、必跑命令未执行。 - -## 6. Cleanliness - -- Debug output: pass/fail -- Temporary TODO/FIXME/XXX: pass/fail -- Commented-out code: pass/fail -- Unused imports / dead code from this feature: pass/fail -- Out-of-scope files: pass/fail - -## 7. Verdict - -- Status: passed|failed|blocked -- Next: `cs-feat-accept` | `cs-feat-impl` qa-fix -> `cs-code-review` -> `cs-feat-qa` | 补齐环境后重跑 `cs-feat-qa` -``` - -没有某类 finding 时写 `none`，不要删除章节；复测要能对比。 - ---- - -## qa-fix 衔接 - -如果 QA `failed`： - -1. 报告 `status: failed`。 -2. 告诉用户下一步触发 `cs-feat-impl` 的 qa-fix 模式。 -3. qa-fix 只修 QA failed / blocked items，不处理顺手发现，不扩大 feature 范围。 -4. qa-fix 修完会改变 diff，必须重跑 `cs-code-review`；review passed 后再重跑 `cs-feat-qa`。 -5. QA passed 后才能进入 `cs-feat-accept`。 - -如果 QA `blocked`： - -- 先补环境 / 输入 / review 状态；不把 blocked 写成通过。 - -如果 QA `passed`： - -- 告诉用户下一步是 `cs-feat-accept`。 - ---- - -## 退出条件 - -- [ ] 已读取 attention、design、checklist、review、实现证据、git status、git diff。 -- [ ] 已确认 review passed 且基于当前 diff。 -- [ ] 已判定 feature type，并写明功能性核心路径或非功能性替代证据理由。 -- [ ] 已建立 verification matrix，覆盖 design 关键场景、必跑命令、review Test And QA Focus、review residual risk、evidence pack commands / residual risks，并标出每项核心性。 -- [ ] 已运行可运行的验证命令 / 浏览器 / API / 手工检查，并记录结果。 -- [ ] 功能性核心路径都有实际运行证据；缺失则 QA 为 failed / blocked，不能写 passed。 -- [ ] 非功能性 feature 如未做 e2e / browser / API，已写明为什么不需要，以及采用了哪些替代证据。 -- [ ] 未运行项都有具体原因和阻塞判断。 -- [ ] 已完成清洁度复核。 -- [ ] 已写 `.codestable/features/{feature}/{slug}-qa.md`。 -- [ ] failed / blocked 时没有进入 acceptance，而是指向 qa-fix 或补环境。 -- [ ] passed 时明确告诉用户下一步 `cs-feat-accept`。 - ---- - -## 容易踩的坑 - -- 把 QA 写成第二次 code review，不运行任何证据。 -- 只跑 typecheck 就宣称前端用户路径通过。 -- 把功能性核心路径没跑过写成 residual-risk，然后仍然 passed。 -- 对文档 / 架构 / 测试补强类非功能性 feature 机械要求 e2e，而不是用更合适的静态 / 一致性 / 目标测试证据。 -- 命令失败但归因不清就写 passed。 -- QA 阶段直接修代码，绕过 qa-fix / review 复审。 -- qa-fix 后跳过 review，直接重跑 QA 或进入 acceptance。 -- 不记录未运行原因，导致 acceptance 无法判断剩余风险。 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-feat` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-feat/SKILL.md b/plugins/codestable/skills/cs-feat/SKILL.md index 89e573c..3e76c21 100644 --- a/plugins/codestable/skills/cs-feat/SKILL.md +++ b/plugins/codestable/skills/cs-feat/SKILL.md @@ -1,6 +1,7 @@ --- name: cs-feat -description: Feature 路由入口。触发：新功能/加 X/实现 XX，按状态进入 design/impl/review/QA/accept。 +description: Feature 主入口。触发：新功能/加 X/实现 XX；端到端推进 design、review、impl、QA、accept。 +argument-hint: "[design|design-review|impl|qa|accept|ff] [需求描述]" --- # cs-feat @@ -9,122 +10,125 @@ description: Feature 路由入口。触发：新功能/加 X/实现 XX，按状 开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 -新功能流程在"需求"和"代码"之间塞了一份方案文件，让两边有交接点——AI 直接拿到需求就写代码会出三个老问题：名字跟原代码对不上、改着改着改出范围、改完不留存档。 +`cs-feat` 是 feature 的唯一推荐入口。用户只需要持续调用本技能；本技能根据仓库事实恢复当前阶段，并在必要 checkpoint 停下来等用户确认。 -``` -(想法模糊先去 cs-brainstorm 分诊) → 方案设计（名词层 + 编排层 + 验收契约 + 推进策略切片）→ 分步实现 → 代码审查 → QA 验证 → 验收闭环 -``` +旧阶段技能长期保留为兼容入口：`cs-feat-design`、`cs-feat-design-review`、`cs-feat-impl`、`cs-feat-qa`、`cs-feat-accept`、`cs-feat-ff`。它们只传入 `requested_stage` 或 `requested_mode`，不维护独立规则。 -brainstorm 是讨论层独立入口，会分诊：case 1（清楚 → 直接 design）/ case 2（小需求继续讨论 → 落 brainstorm note）/ case 3（大需求 → 移交 `cs-roadmap`）。只有 case 2 在 feature 目录产出 brainstorm note。 +--- -本技能不写代码不写文档，只做一件事：看当前 feature 走到哪步，告诉用户该触发哪个子技能。 +## 入口意图 + +本次调用参数：$ARGUMENTS + +意图来源按优先级：调用参数 > 兼容入口预设 > 用户话术。参数为空或未被替换（仍是字面 `$ARGUMENTS`）时跳过该来源；首个 token 命中下表则设为入口意图，其余文本作为需求描述。 + +| token | 入口意图 | +|---|---| +| `design` | `requested_stage: design` | +| `design-review` | `requested_stage: design-review` | +| `impl` | `requested_stage: implementation` | +| `qa` | `requested_stage: qa` | +| `accept` | `requested_stage: acceptance` | +| `ff` | `requested_mode: fastforward` | + +入口意图只是偏好。仓库事实优先：如果已有产物显示当前应先 review、修 QA 或验收，就按事实推进并向用户说明。 --- ## 文件放哪儿 -``` -.codestable/features/{feature}/ -├── {slug}-brainstorm.md ← 阶段 0 产物（仅 case 2 落盘） -├── {slug}-intent.md ← 阶段 1 可选前置草稿（用户自己写半成品） -├── {slug}-design.md ← 阶段 1 方案文件 -├── {slug}-design-review.md ← 阶段 1.5 人审前方案审查报告 -├── {slug}-checklist.yaml ← 阶段 1 生成 steps + checks，2/3 阶段更新 status -├── {slug}-review.md ← 阶段 2.5 代码审查报告 -├── {slug}-qa.md ← 阶段 2.6 QA 验证报告 -└── {slug}-acceptance.md ← 阶段 3 验收报告 +```text +.codestable/features/{YYYY-MM-DD}-{slug}/ +├── {slug}-brainstorm.md +├── {slug}-intent.md +├── {slug}-design.md +├── {slug}-design-review.md +├── {slug}-checklist.yaml +├── {slug}-review.md +├── {slug}-qa.md +├── {slug}-acceptance.md +└── {slug}-ff-note.md # 仅 fastforward 模式 ``` -目录命名 `YYYY-MM-DD-{英文 slug}`，日期取首次创建当天定了不动；slug 小写字母 / 数字 / 连字符。 - -为什么聚一起：以后查"那个导出 CSV 功能当时怎么决定的"，brainstorm / design / review / QA / acceptance 都在一处。feature 和 issue 分别放在 `.codestable/features/` 和 `.codestable/issues/` 因为归档逻辑不一样。 - -实现 feature 时顺手发现的 bug → 记成新 issue，**不在 feature PR 里偷偷修**——验收时分不清范围，git blame 找不到为什么改。 +目录命名取首次创建当天，slug 小写字母 / 数字 / 连字符。标准流程使用 design/checklist/review/QA/acceptance；fastforward 模式只写 `{slug}-ff-note.md`。feature 过程里发现的 bug 另开 issue，不在 feature 里偷修。 --- -## 标准阶段 +## 状态机 -| 阶段 | 子技能 | 产出 | 谁主导 | -|---|---|---|---| -| 0 brainstorm（可选，独立入口） | `cs-brainstorm` | case 2 时产出 brainstorm note | AI 思考伙伴，用户拍板 | -| 1 方案设计 | `cs-feat-design` | design.md + checklist.yaml | AI 起草候选方案 | -| 1.5 方案审查 | `cs-feat-design-review` | design-review.md | Task agent / AI 人审前审查 | -| 2 分步实现 | `cs-feat-impl` | 代码 + 阶段汇报 | AI 按方案执行 | -| 2.5 代码审查 | `cs-code-review` | review.md | AI 只读审查，用户决定是否修 | -| 2.6 QA 验证 | `cs-feat-qa` | qa.md | AI 运行证据，用户确认风险 | -| 3 验收闭环 | `cs-feat-accept` | acceptance.md | AI 逐层核对，用户终审 | +启动后先扫描 `.codestable/features/`、读取目标 feature 的现有产物、检查当前 git diff，再按下表恢复： -阶段间有 gate 和人工 checkpoint。方案先过 design-review，再交给用户整体确认；用户没明确放行，下一阶段别开始——防止 AI 一口气从需求跑到代码、跑出来才发现走偏。 - -阶段 0 可选且是 feature 流程的**外部入口**——`cs-brainstorm` 同时服务 feature 和 roadmap。case 3（大需求）讨论被移交给 `cs-roadmap` 不再回 feature 流程；roadmap 拆出子 feature 后从 `cs-feat-design` 的"从 roadmap 条目起头"入口进来。 - -### Fastforward 模式 - -需求清楚 + 范围小时走标准流程太啰嗦。fastforward 把 design 压成 4 节（需求摘要 / 设计方案 / 验收标准 / 推进步骤），用户一次确认后直接实现。触发："快速模式"、"fastforward"、"直接开干"、"别那么多步骤"，去 `cs-feat-ff`。 - -**别走** fastforward：跨多个子系统、有术语冲突风险、推进步骤超过 4 步——这些情况跳过 design 意味着 AI 和用户没共同确认过同一份方案，实现完容易发现彼此理解不一样。 - ---- - -## 路由：用户现在该走哪个子技能 - -进入本技能先 Glob 一下 `.codestable/features/` 看已有产物。**不要只听用户口头描述**——用户说"设计写完了"不一定真完整，自己读一遍。 - -| 当前状态 | 触发哪个子技能 | +| 仓库事实 | 下一步 | |---|---| -| 想法模糊，说不清真问题 / 边界 / 不做什么 | `cs-brainstorm` | -| 想法清晰（知道做什么 / 为谁 / 怎么算成功） | `cs-feat-design` | -| 用户说"开一个新需求 / 起草稿 / 新建 feature"想自己写半成品 | `cs-feat-design` 的"初始化模式"（建目录 + 空 intent，让用户填完再回） | -| 用户主动说"先 brainstorm 一下"、"有个想法没想清楚" | `cs-brainstorm` | -| `{slug}-intent.md` 已填好 | `cs-feat-design`（读 intent 作输入） | -| 用户说"快速模式 / fastforward" | `cs-feat-ff` | -| `{slug}-brainstorm.md` 已存在，要进设计 | `cs-feat-design` | -| `{slug}-design.md` 是 draft 且没有 `{slug}-design-review.md` | `cs-feat-design-review` | -| `{slug}-design-review.md` changes-requested / blocked | `cs-feat-design` 修订后重跑 `cs-feat-design-review` | -| `{slug}-design-review.md` passed，但 design 还没 approved | 交给用户整体 review，确认后回 `cs-feat-design` 标 approved | -| `{slug}-design.md` 已 approved、代码没动 | `cs-feat-impl` | -| fastforward design 已确认 | `cs-feat-impl` | -| 代码已写完但没有 `{slug}-review.md` | `cs-code-review` | -| `{slug}-review.md` 有 unresolved blocking findings | `cs-feat-impl` 的 review-fix 模式 | -| `{slug}-review.md` 已 passed，但没有 `{slug}-qa.md` | `cs-feat-qa` | -| `{slug}-qa.md` failed / blocked | `cs-feat-impl` 的 qa-fix 模式（修完重跑 review → QA） | -| `{slug}-qa.md` 已 passed，代码要验收 | `cs-feat-accept` | -| 用户直接说"代码已写完要验收"但没有 review 报告 | 先 `cs-code-review`，不要跳到 accept | -| 用户直接说"代码已写完要验收"但没有 QA 报告 | review passed 后先 `cs-feat-qa`，不要跳到 accept | -| 用户说"我想要一个 X 系统"大需求 | 转 `cs-brainstorm` 分诊（大概率 case 3 → `cs-roadmap`） | -| roadmap 里某条子 feature 该启动 | `cs-feat-design` 的"从 roadmap 条目起头"入口 | -| 不确定 design 是否完整 | 自己读一遍，按上面对号 | +| 想法模糊，边界/成功标准/不做什么不清 | 转 `cs-brainstorm` 分诊 | +| 用户要求快速模式且范围小 | 读取 `references/fastforward/protocol.md` | +| 无 design，或已有 intent/brainstorm 要进设计 | 读取 `references/design/protocol.md` | +| design 为 draft 且无 passed design-review | 读取 `references/design-review/protocol.md` | +| design-review changes-requested / blocked | 回 design 修订，再重跑 design-review | +| design-review passed 但 design 未 approved | 停下让用户整体 review；确认后标 `approved` | +| design approved 且代码未完成 | 读取 `references/implementation/protocol.md` | +| 代码完成但无 `{slug}-review.md` | 进入公开横切 gate `cs-code-review` | +| review 有 unresolved blocking | 回 implementation 的 review-fix | +| review passed 但无 `{slug}-qa.md` | 读取 `references/qa/protocol.md` | +| QA failed / blocked | 回 implementation 的 qa-fix，修完重跑 review 和 QA | +| QA passed 但无 acceptance | 读取 `references/acceptance/protocol.md` | +| acceptance passed | 汇报完成状态和后续 docs / neat 候选 | -### 怎么判断该不该走阶段 0 - -判断信号不是"用户描述字数少"，是用户能不能清楚说出三件事：要解决的真问题 / 核心行为 / 一条明确的"不做什么"。三项有一项模糊就值得 brainstorm。 - -但别强推——用户明确说"想清楚了直接做设计"就尊重。不确定时问一句让用户选。**宁可漏判，别误判**——逼一个想清楚的用户做发散是浪费。 - -### brainstorm vs intent - -两者都是 design 前置，区别在**谁在主导收敛**： - -- brainstorm：用户脑子里模糊，AI 问用户答。判 case 3 时移交 `cs-roadmap` 不回 feature；只有 case 2 产出 brainstorm note -- intent：用户自己想好大致做法（100 字描述 + 相关数据结构），懒得口述就写成 `{slug}-intent.md` 给 AI 读 - -用户模糊触发"开一个新需求"时默认问"你想先聊清楚（brainstorm）还是自己写草稿（intent）？"，别自己挑。 +用户说“下一步”时，也按仓库事实而不是聊天历史判断。 --- -## 与 issue 工作流的边界 +## Reference 加载 -- feature：从来没有的东西要加进来（新功能 / 新能力） -- issue：本来应该好的东西坏了（bug / 异常 / 文档错误） +只在进入对应阶段时加载厚规则： -灰色地带：feature 实现时发现的 bug 记成新 issue，不在 feature PR 顺手修。 +- design：`references/design/protocol.md`，必要时 `references/design/reference.md`、`references/design/support/intent-template.md`、`references/design/support/codebase-design.md` +- design-review：`references/design-review/protocol.md` +- implementation：`references/implementation/protocol.md`，必要时 `references/implementation/support/reference.md`、`references/implementation/support/tdd.md` +- code review：公开横切技能 `cs-code-review` +- QA：`references/qa/protocol.md` +- acceptance：`references/acceptance/protocol.md`，必要时 `references/acceptance/reference.md` +- fastforward：`references/fastforward/protocol.md` + +不要把所有 reference 一次性读完；按阶段渐进加载。 --- -## 相关文档 +## 人工 checkpoint -- `.codestable/reference/system-overview.md` — CodeStable 体系总览 -- `.codestable/reference/shared-conventions.md` — 跨阶段共享口径、目录结构、checklist 生命周期 -- `.codestable/attention.md` — CodeStable 启动注意事项和项目硬约束 -- `.codestable/requirements/CONTEXT.md` + `requirements/adrs/` — 方案设计阶段需要查的领域术语与拍板决策 +必须停下等用户明确确认的点： + +1. design-review passed 后的 design 整体确认。 +2. implementation 完成后的 code review 结果处理。 +3. QA failed / blocked 后的修复方向。 +4. acceptance 最终结论与长期文档回写风险。 + +本技能是连续编排入口，不是无确认自动到底。 + +--- + +## Fastforward + +`requested_mode: fastforward` 只表示用户想走快速模式。进入前仍要确认范围小、需求清楚、无跨系统术语/契约风险。若不满足，解释原因并回标准 design 流程。 + +fastforward 产物固定为 `.codestable/features/{YYYY-MM-DD}-{slug}/{slug}-ff-note.md`，不生成标准 design/checklist/QA/acceptance 套件。 + +`cs-feat-ff` 是兼容入口，不再单独维护快速模式规则。 + +--- + +## 退出条件 + +- 当前阶段产物已落盘，状态可由仓库事实恢复。 +- 阻塞项、用户 checkpoint 或下一阶段已明确说明。 +- 标准流程最终需要 design approved、review passed、QA passed、acceptance passed。 +- 需要外部文档时提示 `cs-docs`；需要阶段收尾/记忆同步时提示 `cs-docs-neat`。 + +--- + +## 相关入口 + +- `cs-code-review`：实现后的横切只读审查 gate。 +- `cs-docs`：对外教程 / API 参考文档。 +- `cs-docs-neat`：阶段收尾和知识库同步。 +- `cs-epic`：大需求拆分与 goal 执行包。 diff --git a/plugins/codestable/skills/cs-feat/references/acceptance/protocol.md b/plugins/codestable/skills/cs-feat/references/acceptance/protocol.md new file mode 100644 index 0000000..3e44859 --- /dev/null +++ b/plugins/codestable/skills/cs-feat/references/acceptance/protocol.md @@ -0,0 +1,280 @@ +# Feature Acceptance Protocol + +代码已经写完，但流程没结束。本阶段做四件事，缺一不可： + +1. **核对实现有没有偏离方案**——逐层对照 `{slug}-design.md`，发现偏差当场修，**不是在报告里"记一下"**就过去 +2. **盘点领域影响**——识别本次是否引入新术语 / 结构性决策，提示用户走 `cs-domain` 写 CONTEXT.md / ADR（不在 accept 里代写） +3. **能力落档到 requirement**——draft req 对应的能力实现完成后升级为 current（保留愿景，追加变更日志）；从未写过 req 的能力 backfill +4. **完成状态回写到 roadmap**——方案 frontmatter 有 `roadmap` / `roadmap_item` 字段时**必须**改 items.yaml 对应条目为 `done` 并同步主文档 + +漏掉任何一件的代价：CONTEXT.md / adrs/ 没跟上下个 feature 读到错术语；req 和实际能力脱节；roadmap 规划层和实际进度脱节，下次推进会重复跑流程。 + +**验收原则**：acceptance 是最终审计，不是实现汇报的整理。要重新读取原始 design 和 checklist，以最终工作区为准逐项复验；实现阶段说通过只能当线索，不能当结论。发现缺口要先修代码 / 方案 / 文档并重验，再写通过。 + +**推进原则**：验收阶段要用仓库事实关闭任务，而不是用对话自述关闭任务。最终结论必须回答四个问题：原始契约是否满足、验证证据是否足够且在最终状态仍成立、承诺交付物是否真实落盘、这次学到的可复用知识是否进入 CodeStable 的沉淀出口。 + +**独立审计边界**：可按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动只读 acceptance auditor，复核 design/checklist/review/QA/final diff 和状态回写候选；但 auditor 只能返回 findings，不得写 `{slug}-acceptance.md`、checklist、roadmap、requirement 或状态文件。acceptance 是流程关闭动作，最终 verdict、状态推进和文件写入必须由当前主流程 owner 完成。 + +**没产出报告 = 工作流未完成**。后人查"上次这个功能验收时确认了哪些行为"，没报告就只能翻 git diff 重新推断。 + +> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md` 第 0 节。 +> +> 本阶段默认 **L3**，遵守 Global Route Governance：不在 accept 阶段自由重写长期 requirement，capability-boundary 变化必须先有 owner-approved req delta，缺 delta 就停下写 `approval-report.md`。详见同目录 `reference.md`。 + +--- + +## 跟 design 的章节强依赖 + +本阶段整套对照表按 design 当前章节编号硬编码。**design 升级章节名 / 编号时本协议必须同步**，否则下面所有"第 X 节"指针都指错地方。 + +**标准 design 章节快照**： + +- 第 0 节：术语约定 +- 第 1 节：决策与约束（需求摘要 / 复杂度档位 / 关键决策 / 前置依赖） +- 第 2 节：名词与编排（2.1 名词层 / 2.2 编排层 / 2.3 挂载点 / 2.4 推进策略） +- 第 3 节：验收契约（关键场景清单 + 反向核对项） +- 第 4 节：领域影响（新术语 / 结构性决策 / 流程级约束） + +**Fastforward design**：第 0 需求摘要 / 第 1 设计方案 / 第 2 验收标准 / 第 3 推进步骤 + +--- + +## 启动检查 + +1. **代码确实实现到位**——git status / 最近提交看到本功能改动，否则退回 implement +2. **方案 doc 完整**——frontmatter `doc_type=feature-design` / `feature` 一致 / `status=approved` / `summary` 非空 / `tags` ≥ 2；标准 design 第 0/1/2/3 节 + 第 4 节已填写 +3. **`{slug}-checklist.yaml`**——存在且 `feature` 一致；`steps` 全 `done`（有 `pending` 退回 implement）；`checks` 非空全 `pending` +4. **`{slug}-review.md`**——存在且 frontmatter `doc_type=feature-review`、`status=passed`；没有 unresolved `blocking` findings。缺失 → 先跑 `cs-code-review`；有 blocking → 退回 `cs-feat` implementation 阶段 review-fix；status 不是 passed → 不进入验收 +5. **Gate / DoD evidence**——goal / gate 模式下读取 `{slug}-evidence-pack.md`、`{slug}-gate-results.json`、`{slug}-dod-results.json`；缺失或 blocking DoD 无 pass evidence 时退回 implementation gate。 +6. **验证证据来源**——独立 `cs-feat` QA 阶段 不是 standalone accept 的硬前置；但验收必须有同等强度的验证证据： + - 已有 `{slug}-qa.md`：读取并复核。frontmatter 必须 `doc_type=feature-qa`、`status=passed`；failed / blocked → 退回 `cs-feat` implementation 阶段 qa-fix；status 不是 passed → 不进入验收。 + - 没有 `{slug}-qa.md`：不要强制切去跑 `cs-feat` QA 阶段。在本次 accept 里建立 `Inline Verification Matrix`，对照 design 第 3 节、checklist checks、review Test And QA Focus / residual risk 和项目测试入口，现场运行验证，并把证据写入 acceptance 第 3 节和第 10 节最终审计。这个模式等价于“accept-inline QA”，但不额外生成 QA 报告。 + - Goal 模式例外：`cs-epic` goal 阶段 协议明确要求逐 feature 生成 QA 报告；在 goal 模式缺 `{slug}-qa.md` 时按 goal protocol 停止，不走 accept-inline。 +7. **核心证据复核**——不管证据来自 QA 报告还是 accept-inline，都按同一标准复核： + - 功能性或 mixed feature：design 第 3 节、checklist checks、review QA focus 中的核心功能路径必须有运行证据。若核心路径未运行、真实用户/API/运行时路径未验证、必跑命令未执行，acceptance 必须写 `status=blocked`。下一步按原因选择：代码/测试缺口 → `cs-feat` implementation 阶段 qa-fix 后重跑 review 和 accept-inline；环境缺口 → 先补环境；用户希望独立 QA 报告 → 跑 `cs-feat` QA 阶段。 + - 非功能性 feature：不要求 e2e / browser / API，但必须写明为什么不需要端到端运行，并提供静态检查、diff 复核、文档一致性、schema/快照/类型/构建/目标测试等替代证据。缺说明或证据不足时继续补证据，不直接通过。 +8. **上下文读全**——方案 doc 全文（重点：第 1 节明确不做、2.1 接口示例、2.2 流程级约束、2.3 挂载点、第 3 节场景）+ checklist + review 报告（findings / residual risk / Test And QA Focus）+ QA 报告（如有：Feature type / Core evidence gate / Verification Matrix / Command Results / Scenario Results / residual-risk）+ evidence pack / DoD results / Gate results + accept-inline 验证矩阵（如无 QA 报告）+ implement 完成汇报里的基线预检 / step 证据 / 实际交付物索引 / 知识回写候选 + 第 4 节提到的领域影响候选 + `requirements/CONTEXT.md` + 相关 ADR + 本次代码改动（git log / diff） +9. **断点恢复**——`{slug}-acceptance.md` 已存在且部分填好 → 从下一个未完成节继续，跳过 checks 中已 `passed` 的项；汇报"上次做到第 X 节，从第 Y 节继续" + +**Fastforward design 验收报告映射表**： + +| 验收报告节 | 标准 design 对照 | Fastforward design 对照 | +|---|---|---| +| 1 接口契约核对 | 第 2.1 接口示例 | 第 1 节改动点 | +| 2 行为与决策核对（含挂载点） | 第 1 节 + 第 2.2 + 第 2.3 | 第 0 节；挂载点现场盘点 | +| 3 验收场景核对 | 第 3 节场景清单 + 反向核对 | 第 2 节验收标准 | +| 4 术语一致性 | 第 0 节 + 第 2.1 命名 | 检查代码命名一致性 | +| 5 领域影响盘点 | 第 4 节 | 通常无；写"无领域维度变更" | + +--- + +## 验收报告模板 + +逐节填写**别跳节**。报告路径在 feature 目录下（位置看 `shared-conventions.md` 第 0 节）。 + +```markdown +--- +doc_type: feature-acceptance +feature: YYYY-MM-DD-slug +status: passed|blocked +accepted: YYYY-MM-DD +round: 1 +--- + +# {功能名称} 验收报告 + +> 阶段：阶段 3（验收闭环） +> 验收日期：YYYY-MM-DD +> 关联方案 doc：{方案 doc 路径} + +## 1. 接口契约核对 + +对照方案第 2.1 节名词层逐一核查： + +**接口示例逐项核对**： +- [ ] 示例 A（{文件路径 + 函数名}）：示例输入→输出 → 代码实际行为：{一致 / 偏差说明} + +**名词层"现状 → 变化"逐项核对**： +- [ ] 名词 X：声称的变化 → 代码改动：{一致 / 偏差} + +**流程图核对**（第 2.2 节开头 mermaid 图）： +- [ ] 图中节点 / 调用关系在代码均有实际落点（grep 确认） + +发现偏差**先修代码或回填方案 doc**。报告里写"已知偏差暂不处理"是反模式——下次按方案找代码会被绊倒。 + +## 2. 行为与决策核对 + +对照方案第 1 节 + 第 2.2 节： + +**需求摘要逐项验证**： +- [ ] 行为 A：{描述 + 实测结果} + +**明确不做逐项核对**（用第 3 节"反向核对项"）： +- [ ] 范围外事项 X **确实没做**（grep / review 确认） + +**关键决策落地**： +- [ ] 决策 D1：{决策内容} → 代码体现：{描述} + +**编排层"现状 → 变化"逐项核对**： +- [ ] 变化 V1：{在哪一步插入 / 哪条分支变更} → 代码实际落点 + +**流程级约束核对**（错误语义 / 幂等 / 并发 / 扩展点 / 可观测点）： +- [ ] 纪律 R1：{描述} → 代码遵守方式 + +**挂载点反向核对（可卸载性）**——对照第 2.3 节，必做两件事： +- [ ] 挂载点 M1：清单条目 → 代码实际落点：{一致 / 偏差} +- [ ] **反向核查**（grep）：本 feature 在代码里的所有引用是否都落在清单内？清单外的引用 → 漏记，补进第 2.3 节 +- [ ] **拔除沙盘推演**：按清单逆向操作后是否还有残留？残留 → 写进"遗留"或补挂载点 + +Fastforward 方案没有挂载点清单 → 现场 grep 盘点本次改动命中的挂入位置作为卸载依据。 + +## 3. 验收场景核对 + +对照方案第 3 节关键场景清单，逐条可观察证据验证： + +- [ ] **S1**：{场景"输入 / 触发 → 期望可观察结果"} + - 证据来源：{类型系统 / 单测 / 集成 / 手工 / 肉眼} + - 结果：{通过 / 未通过 + 原因 + 补救} + +**功能性前端改动必须浏览器肉眼验证**（typecheck 通过不代表用户用起来对；非功能性前端改动用替代证据复核）： +- [ ] UI 区域 X：浏览器验证 OK / 截图链接 + +**review 报告重点复核**： +- [ ] `{slug}-review.md` 第 4 节 Test And QA Focus 已逐条覆盖 +- [ ] `{slug}-review.md` 第 5 节 residual risk 已逐条处理 / 明确留作用户确认遗留 + +**QA 报告重点复核**： +- [ ] 验证证据来源：`{slug}-qa.md` / accept-inline verification +- [ ] QA 报告或 Inline Verification Matrix 已覆盖 design 关键场景和 review QA focus +- [ ] QA 报告或 Inline Verification Matrix 中的 feature 性质与核心证据说明合理：功能性核心路径有运行证据；非功能性 feature 有替代证据理由 +- [ ] failed / blocked 项为 none +- [ ] residual-risk 已逐条处理 / 明确留作用户确认遗留，且没有承载核心验收缺口 +- [ ] Evidence pack、DoD Results、Gate Results 已复核；blocking DoD 均有 pass evidence + +## 4. 术语一致性 + +对照方案第 0 节 + 第 2.1 节命名 grep 代码： + +- 术语 X：代码命中 N 处全部一致 ✓ +- 防冲突：禁用词 grep 无命中 ✓ + +发现不一致 → 改代码，别在报告里写"已知差异"。 + +## 5. 领域影响盘点（提示而非代写） + +**目标**：识别本次 feature 是否引入了应进 CONTEXT.md / adrs/ 的内容，**提示用户走 cs-domain**——不在 accept 里替它写。 + +对照方案第 4 节 + 实际实现，三类信号逐项盘点： + +- **新名词** → `requirements/CONTEXT.md` 候选：新增 / 改名的实体、类型、对外契约；grep CONTEXT.md 看是否已有定义，没有就提示"走 cs-domain 加术语？" +- **结构性选择**（满足 ADR 3 判据：难回退 + 不显然 + 真权衡）→ `requirements/adrs/` 候选：新增模块 / 跨模块接口模式 / 新依赖选型 / 拒绝的备选 +- **流程级约束** → `requirements/adrs/` 候选：稳定的错误语义 / 幂等约束 / 扩展点规约 + +逐项核对： +- [ ] 候选 X（{术语 / 结构选择 / 流程约束}）：建议 {cs-domain 写 CONTEXT / 写 ADR} → 已建议用户 ✓ / 不需要（理由：{具体}） + +**不在 accept 里直接改 CONTEXT.md 或写 ADR**——这是 cs-domain 的事。accept 只盘点 + 建议。本节是登记表，不是动作。 + +## 6. requirement delta / clarification 回写 + +req 是能力愿景层，但 **accept 阶段不自由重写长期 requirement**（Global Route Governance，本阶段 L3）。对照方案 frontmatter 的 `requirement`、第 1 节需求摘要、feature 目录下已有 `*-req-delta.md` 与 clarifications： + +- 纯重构 / 无 requirement 影响 → 写"无 requirement 影响"，跳过。 +- 新增了用户可感能力，或改了边界 / 用户故事 / pitch：**必须有 owner-approved req delta** 才机械应用（`draft`→`current` 或刷新 current，保留原始愿景 + 变更日志）；**没有 approved delta 就停下**写 `approval-report.md`，回 clarification / `cs-req` delta 流程，不在 accept 里直接落 current。 +- `requirement` 指向 current 但本次未改用户视角 → 写"req-{slug} 未变"。 + +完整 7 分支判据与 Global Route Governance 全文见同目录 `reference.md`。这是受 delta 约束的实际写文件动作，不是把 accept 当成自由重写 requirements 的机会。 + +## 7. roadmap 回写 + +对照方案 frontmatter 的 `roadmap` / `roadmap_item`： + +- [ ] 两字段都空（feature 未从 roadmap 起头）→ 跳过，写"非 roadmap 起头" +- [ ] 两字段都有值： + - 打开 `.codestable/roadmap/{roadmap}/{roadmap}-items.yaml` + - 找到 `slug: {roadmap_item}`，核对当前 `status: in-progress` + `feature: {目录名}`——不对停下来找原因 + - 改 `status: done`，用 `validate-yaml.py` 校验 + - 同步 `{roadmap}-roadmap.md` 主文档第 3 节子 feature 清单的对应条目状态 +- [ ] 两字段不一致（只填了一个）→ 停下来补齐或澄清 + +衔接协议看 `shared-conventions.md` 第 2.5 节。和 req 同规则：实际写文件的动作。 + +## 8. attention.md 候选盘点 + +回看本次实现，结合 implement 完成汇报里的"知识回写候选"，盘点"每个 feature 都会撞一次"的环境 / 工具 / 工作流类信息。典型候选：编译命令、代理配置、本地起服务步骤、反复踩的环境坑、仓库内非显然的工作流约定。 + +**判据**：下一个 feature 的 AI 还会再踩一次的事才记。一次性踩坑、和具体业务耦合的细节归 learning / decide。 + +- [ ] 无候选：写"本 feature 未暴露需要补入 attention.md 的内容" +- [ ] 有候选：列出来，**不擅自写入**——本节只登记，落不落由用户在"退出后"环节定 + - 候选 1：{描述 + 建议放 attention.md} + +同时分流其他知识出口： + +- 稳定技术约束 / 目录归属 / 命名规约 / 可复用坑点 / 库 API 经验 / 调试路径 → 第 9 节遗留或退出后提示 `cs-keep` +- 用户操作指南或开发者指南变化 → 退出后提示 `cs-docs` tutorial 模式 +- 公开 API / 组件 / 命令表面变化 → 退出后提示 `cs-docs` api 模式 + +## 9. 遗留 + +- 后续优化点（已开 issue 或加入 issue 列表）：{列表} +- 已知限制：{列表} +- 实现阶段"顺手发现"列表：{列表} +``` + +--- + +## 核对节奏 + +逐节做。每节完成后**逐条更新 `{slug}-checklist.yaml` 的 `checks`**：通过 → `passed`，失败 → `failed`（先修代码 / 方案再改回 `passed`）。所有 checks 全 `passed` 后报告才算完成。 + +第 1/2 节最容易暴露偏离，先做。第 2 节挂载点反向核对**必须实际 grep + 沙盘推演**，不能凭印象勾选。第 5/6/7 节是写文件的动作，不是自评。 + +## 最终审计节奏 + +9 节报告填完、checks 全部 `passed` 之后**还不能直接宣布完成**，再跑一轮 final audit 用最终工作区反查原始设计：重读原始契约、聚合命令复验、场景抽样复核、交付物 / 完整工作区 / diff 清洁度 / 知识沉淀复核、覆盖率诚实标记（写 `re-verified` / `trust-prior-verify` 数）。发现缺口先把对应 check 改回 `failed`、只修失败项、重跑对应节与 final audit；同一缺口三轮仍失败则停下交还用户，不写"通过"。 + +**完整 8 步、缺口处理与「## 10. 最终审计」报告模板见同目录 `reference.md`**。验收报告在第 9 节后追加第 10 节最终审计。 + +--- + +## 退出条件 + +- [ ] 验收报告 9 节都填完 +- [ ] review 报告存在且 `status=passed`，无 unresolved blocking findings +- [ ] 验证证据来源已明确：QA 报告 passed，或 acceptance 第 3 / 10 节已有 accept-inline verification matrix +- [ ] 验证证据中没有 unresolved failed / blocked items +- [ ] 没有把功能性核心路径未验证、真实用户/API/运行时路径未运行、必跑命令未执行写成 residual-risk 后放行；非功能性 feature 的替代证据理由已复核 +- [ ] 第 1/2 节核对全部勾选，无未处理偏差（含挂载点 grep + 拔除沙盘推演） +- [ ] 第 3 节场景核对全部勾选；功能性前端已浏览器验证，非功能性前端已有替代证据 +- [ ] 第 4 节术语一致性无遗漏 +- [ ] 第 5 节领域影响盘点：每条候选有明确结论（已建议 cs-domain / 不需要） +- [ ] 第 6 节 req 回写有结论：跳过 / 未变 / 已 backfill / draft→current / 已 update +- [ ] 第 7 节 roadmap 回写有结论：跳过（非 roadmap 起头）/ 已更新（items.yaml + 主文档同步，yaml 通过校验） +- [ ] checklist 所有 checks 都 `passed` +- [ ] 最终审计已完成：聚合命令重跑、完整工作区复核、交付物落盘复核、diff 清洁度复核、知识沉淀出口分流、re-verified / trust-prior-verify 已记录；无未处理缺口 +- [ ] 用户终审确认 + +--- + +## 退出后 + +告诉用户："验收报告已就绪，领域影响候选已盘点，cs-feat 工作流走完。后续 BUG 走 issue 流程。" + +按 `shared-conventions.md` 第 3 节收尾推荐顺序逐项一句话提示（用户说"不用"立刻跳过）： + +1. 复用价值的坑点 / 经验 / 长期约束 / 技术选型 → "沉淀到 compound？（`cs-keep`）" + - **特检**：design 第 2.5 节是否有"建议沉淀的 convention"段。有就把那条规则原文念给用户："design 2.5 建议沉淀这条 convention：『{规则一句话}』，跑通了，要不要现在 `cs-keep` 归档？"——这种是 design 阶段就识别出的稳定模式，比一般"问问看"更应该主动提 +2. 接口变更 / 用户可见行为变更 → "需要更新指南吗？（`cs-docs` tutorial 模式）" +3. 库公开接口（组件 / 函数 / 命令）变了 → "需要更新 API 参考吗？（`cs-docs` api 模式）" +4. 第 8 节有 attention.md 候选 → 逐条问"候选 X 加到 attention.md 吗？" 用户明确同意 → 触发 `cs-note` 走分节归类 / 查重 / 软上限检查（不在 accept 里手写，避免和 cs-note 各搞一套口径）；**一次一条** +5. 阶段 / 里程碑收尾、准备交接，或本次改动影响 README/docs、`CLAUDE.md` / `AGENTS.md`、agent 记忆 → "要做一轮文档与记忆整理吗？（`cs-docs-neat`）" +6. 最后问是否代为 scoped-commit + +收尾提交规则看 `shared-conventions.md` 第 4 节。提交范围：功能代码 + 方案 doc + 验收报告 + 本次实际更新的 req doc / CONTEXT.md / ADR / roadmap items.yaml + 主文档。 + +--- + +## 容易踩的坑 + +常见坑（测试/QA passed ≠ 验收场景满足、挂载点要 grep 不能只看清单、领域盘点是当下动作不是建议、accept 不直接改 CONTEXT.md 或写 ADR——那是 cs-domain 的事，accept 只盘点 + 建议、final audit 缺口要先修不能写"遗留"、accept 不自由重写 requirement 必须走 delta、未经用户终审 / 同意不宣告完成或 commit 等）见同目录 `reference.md`。 diff --git a/plugins/codestable/skills/cs-feat-accept/reference.md b/plugins/codestable/skills/cs-feat/references/acceptance/reference.md similarity index 94% rename from plugins/codestable/skills/cs-feat-accept/reference.md rename to plugins/codestable/skills/cs-feat/references/acceptance/reference.md index 1d52864..d7a3481 100644 --- a/plugins/codestable/skills/cs-feat-accept/reference.md +++ b/plugins/codestable/skills/cs-feat/references/acceptance/reference.md @@ -1,8 +1,8 @@ -# cs-feat-accept 参考 +# Feature Acceptance Reference ## Global Route Governance -`cs-feat-accept` 默认是 L3：它可能写长期 architecture / requirement / roadmap 状态，并决定 feature 是否可进入 finish / merge。必须遵守全局 route governance： +`cs-feat` acceptance 阶段默认是 L3：它可能写长期 architecture / requirement / roadmap 状态，并决定 feature 是否可进入 finish / merge。必须遵守全局 route governance： - requirement 不允许在 accept 阶段自由重写； - capability-boundary 变化必须先有 owner-approved requirement delta； @@ -63,7 +63,7 @@ final audit 发现任何缺口： ## 容易踩的坑 - "测试都过了" → 测试通过 ≠ 验收场景满足，要逐条核对第 3 节 -- "没跑过 cs-feat-qa 所以不能 accept" → 不对。standalone accept 可以现场补同等验证证据；goal 模式才强制独立 QA 报告 +- "没跑过 `cs-feat` QA 阶段所以不能 accept" → 不对。standalone accept 可以现场补同等验证证据；goal 模式才强制独立 QA 报告 - "QA passed" → QA frontmatter 通过 ≠ 可直接验收；还要确认功能性核心路径没有被塞进 residual-risk，非功能性 feature 的替代证据足够 - "我肉眼看了一下" → 按清单走，逐项勾选 - 接口偏差在报告里写"已知偏差"而不修代码 / 回填方案 diff --git a/plugins/codestable/skills/cs-feat/references/design-review/protocol.md b/plugins/codestable/skills/cs-feat/references/design-review/protocol.md new file mode 100644 index 0000000..82882e4 --- /dev/null +++ b/plugins/codestable/skills/cs-feat/references/design-review/protocol.md @@ -0,0 +1,281 @@ +# Feature Design Review Protocol + +本阶段是 feature design 交给用户人工确认前的方案审查 gate。它只读 design、checklist、相关文档和必要代码事实，只写 `{slug}-design-review.md`，不直接改 design/checklist、不替用户批准 design、不进入实现。 + +目标不是替用户做产品判断，而是确认这份 design 已经具备让用户有效 review 和让下游稳定执行的条件：需求边界可核对、名词层和编排层有代码事实支撑、steps 可独立验证、checks 能回到 design 证据、风险 / 基线 / 交付物 / 清洁度可被后续 implement、code review、QA 和 acceptance 消费。 + +> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。feature design 的具体结构以目标 `{slug}-design.md` / `{slug}-checklist.yaml` 和项目内共享口径为准。 +> 报告语言：design-review 报告正文必须按 `.codestable/attention.md` 用**中文**；若草稿用了英文，落盘前先改写为中文。frontmatter / yaml 字段不翻译。 + +--- + +## 输入 + +进入 review 前必须读取： + +- `.codestable/attention.md` +- `.codestable/features/{feature}/{slug}-design.md` +- `.codestable/features/{feature}/{slug}-checklist.yaml` +- 同目录的 `{slug}-intent.md` / `{slug}-brainstorm.md`（如果存在） +- design frontmatter 指向的 requirement 文档 +- design frontmatter 指向的 roadmap 主文档和 items.yaml（如果有 `roadmap` / `roadmap_item`） +- design 第 4 节指向的 architecture 文档 +- 相关 compound 沉淀：用项目搜索工具按 feature 关键词检索 decision / learning / explore / trick +- design 中引用到的关键代码位置、接口、类型、组件、命令、配置 +- 独立 Task agent reviewer 输出（如果本轮已启动） + +没有代码引用时不强行扫全仓库；但 design 声称复用、修改、挂载或约束某个现有模块时，必须读对应代码或文档事实核验。 + +--- + +## 启动检查 + +1. design 存在，frontmatter `doc_type=feature-design`，`feature` 与目录一致，`status` 通常是 `draft`；复审已 approved 设计时要确认用户确实要求重新审查。 +2. checklist 存在，`feature` 与目录一致，`steps` 非空，`checks` 非空；缺 checklist 时报告 `blocked`，回 `cs-feat` design 阶段 生成 review candidate checklist。 +3. checklist 的 `steps.status` 和 `checks.status` 在人审前都应是 `pending`；已有 `done/passed` 说明阶段混乱，报告 `blocked`。 +4. 从 roadmap 起头时，roadmap item 必须能在 items.yaml 中找到，design 的 `roadmap_item` 与 feature slug 对齐。 +5. 如果已有 `{slug}-design-review.md`： + - `status: passed` 且 design/checklist 未变化：提示可进入用户整体 review。 + - `status: changes-requested` / `blocked`：读取旧 findings，确认是否复审。 + - design/checklist 已变化：重新 review，并在报告里记录轮次。 + +--- + +## 独立 Task agent reviewer gate + +本阶段必须优先启动独立 Task agent reviewer；当前 agent 的本地审查只能作为合并与事实核验，不能替代独立审查。只有运行时确实没有 Task agent 能力、provider 不可用且无法配置，或用户在看到降级风险后明确授权，才允许 `local-only` / `skipped-by-user`。批量 design、赶时间、主 agent 自认为风险低，都不是降级理由；需要授权降级时，先按 `.codestable/reference/approval-conventions.md` 写 `approval-report.md`，再让用户选择。 + +一旦本轮应该启动或已经启动独立 Task agent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 reviewer 返回前定稿 `{slug}-design-review.md`、不能给出 `passed`、不能把 design 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。 + +**检测由主 agent 在运行时自检自己的工具**，不靠脚本猜环境——主 agent 最清楚自己手上有哪些工具。按 Task agent 选择规则启动独立 Task agent reviewer（优先 Paseo subagent，否则当前宿主原生 Codex/Claude Task/Agent）： + +1. **有 `mcp__paseo__create_agent` 工具**：必须优先用 Paseo subagent 做只读独立审查（首选：能换 provider，做到真正异构审查）。启动前先加载 / 读取 `paseo` skill 的当前说明，并遵守它的规则：读取 `~/.paseo/orchestration-preferences.json`，使用 `providers.audit`，不要硬编码 Claude 或 Codex。不要无限轮询运行中的 agent；如果 reviewer 已启动但结果未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。 +2. **否则有当前宿主原生 Codex/Claude Task/Agent 工具**：用原生 Task agent 做独立上下文审查。如属同类 agent，在报告里记录降级和残余风险。 +3. **两者都没有**：本地 review 只能在记录 `local-only` 且获得必要授权后定稿；没有授权时报告 `blocked`，不要伪装启动。 + +独立 Task agent reviewer prompt 必须只给原始材料和边界，不透露本地 review 结论： + +```text +你是 CodeStable feature design 的独立方案审查 agent。只读，不修改文件，不更新 design/checklist。 + +请读取： +- .codestable/attention.md +- {design_path} +- {checklist_path} +- 同目录 intent / brainstorm（如有） +- 相关 roadmap / requirement / architecture / compound 文档 +- design 引用到的关键代码、接口、类型、组件、命令入口 + +按 feature design review 的严重度语义输出：blocking / important / nit / suggestion / learning / praise / residual-risk。 +重点审查：需求边界、术语冲突、名词层现状→变化、module interface depth / seam / adapter、编排层流程、挂载点可卸载性、结构健康度、验收契约、steps 原子性、checks 来源、基线与验证命令、交付物、清洁度、roadmap 接口契约遵守情况。 +每条 finding 必须有 design/checklist/doc/code 事实证据、影响、建议修复边界。 +不要写 {slug}-design-review.md；只把审查结果回传给主 agent。 +``` + +主 agent 仍是最终审查责任方：必须逐条核验独立 Task agent reviewer 的 finding，去重、定级、合并进 `{slug}-design-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。 + +--- + +## 审查流程 + +### 1. 范围与事实 + +- 用 design 第 0/1 节确认术语、需求摘要、明确不做、复杂度档位、关键决策。 +- 用第 2.1 / 2.2 节确认名词层和编排层是否都有"现状 → 变化"，且现状指向真实代码 / 文档。 +- 用第 2.3 节确认挂载点是否按"删掉 feature 是否消失"收紧。 +- 用第 2.4 节和 checklist steps 对齐推进策略、退出信号和验证动作。 +- 用第 2.5 节确认结构健康度评估覆盖文件级 + 目录级，微重构只做"只搬不改行为"。 +- 用第 3/4 节确认验收契约、架构回写预判、证据类型。 +- 从 roadmap 起头时，额外核对 roadmap 第 4 节接口契约是硬约束，design 没有私自绕开。 + +### 2. 独立审查合并 + +- 记录主 agent 自检结果：`paseo` / `native-agent` / `local-only`。 +- 没有启动独立 Task agent reviewer 时，记录确无能力 / provider 不可用 / 用户授权降级；未满足这些条件时不得定稿 `passed`。 +- 启动 Paseo subagent / 原生 Task agent 后，最终 verdict 必须等 reviewer 返回。 +- reviewer 返回后逐条做本地事实核验；能用 design / checklist / 文档 / 代码证据支撑才合并。 +- reviewer 失败、权限阻塞、超时或仍在运行时，不要默默降级；报告 `status: blocked`。 + +### 3. 方案审查 + +至少覆盖： + +- 需求边界：用户目标、核心行为、成功标准、明确不做是否可核对。 +- 术语与现状：关键术语是否与代码 / 架构 / 历史 feature 冲突；现状描述是否真实。 +- 名词层：值对象、实体、接口、类型、组件 props/events 是否讲清变化。 +- Module/interface 设计：interface 是否包含 caller 必须知道的 invariant / ordering / error mode；module 是否 deep；seam / adapter 是否真实需要；测试是否能通过 interface 观察行为。 +- 编排层：主流程图、分支、错误语义、幂等、并发、可观测点是否能跑通。 +- 挂载点：是否列了真实对外注册点，而不是内部改动文件清单。 +- 结构健康度：微重构是否必要且边界安全；目录 convention 候选是否合理。 +- 验收契约：正常 / 边界 / 错误路径是否覆盖，是否有证据类型。 +- checklist：steps 是否独立可验证，exit_signal 是否 yes/no，checks 是否都能追溯到 design。 +- 基线与验证：必跑命令、预检策略、基线红灯归因是否写清。 +- 交付物与清洁度：acceptance 是否能从仓库事实核验；调试输出、TODO、死 import 等规则是否明确。 + +### 4. Feature Design Review Invariants 与证据分级 + +每轮 review 必须形成 Evidence Confidence Ledger。证据分级只描述依据来源，不计算质量分： + +- `E` Embedded：design / checklist / roadmap item / 命令输出里直接可见。 +- `C` Context：相关 req / arch / compound / 代码事实支撑。 +- `H` Heuristic：工程经验或 reviewer 判断，缺少直接仓库证据。 + +核心 invariants： + +- Acceptance Coverage Matrix 覆盖每个核心验收场景。 +- 每个核心场景能追踪到 checklist step、证据类型和命令 / 动作。 +- checklist steps 独立可验证，checks 能回到 design 来源。 +- roadmap 起头的 design 没有绕开 roadmap 接口契约。 +- DoD Contract 覆盖 Design / Implementation / Review / QA / Acceptance DoD、Validation Commands 和 Required Artifacts。 +- Module/interface design 覆盖 depth、seam placement、dependency strategy；没有新增 / 改动 interface 时可标 not-applicable。 +- checklist `dod.commands` 若存在，字段使用 `{id, command, core, failure_handling}`；design 表格只是人读投影。 +- 核心检查若只有 `H` 证据，不能静默 `passed`；至少写入 residual risk，必要时列 important / blocking finding。 + +--- + +## 严重度 + +- `blocking`：必须先修。会导致 design 不能被用户有效 review、实现无稳定契约、roadmap 契约被绕开、steps/checks 无法执行、验收不可证伪、关键风险没有验证路径。 +- `important`：应该修；若用户决定延后，必须在 design review 和用户 review 摘要中明确记录。 +- `nit`：小的清晰度或一致性建议，不阻塞。 +- `suggestion`：替代设计思路或补强建议，不要求本次采用。 +- `learning`：知识性说明，不要求动作。 +- `praise`：记录值得保留的设计做法；少量即可。 +- `residual-risk`：review 无法完全消除的不确定性，需要用户 review、implementation、code review、QA 或 acceptance 重点复核。 + +不要把个人偏好的实现写法升级成 blocking。blocking 必须能用 design 契约、checklist、roadmap/req/arch、代码事实或可靠工程原则支撑。 + +--- + +## 报告模板 + +报告路径：`.codestable/features/{feature}/{slug}-design-review.md`。 + +```markdown +--- +doc_type: feature-design-review +feature: {feature} +status: passed|changes-requested|blocked +reviewed: YYYY-MM-DD +round: 1 +--- + +# {slug} feature design 审查报告 + +## 1. Scope And Inputs + +- Design: {path} +- Checklist: {path} +- Intent / brainstorm: {path / none} +- Roadmap: {path / none} +- Related docs: {requirements / architecture / compound} +- Code facts checked: {paths / none} + +### Independent Review + +- Status: not-available|skipped-by-user|local-only|pending|completed|failed|blocked +- Detection: paseo|native-agent|local-only|skipped +- Provider / agent: {providers.audit / agent id / none} +- Raw output: {摘要 / 路径 / none} +- Merge policy: {已逐条核验 / 未启用原因 / pending 时不得定稿} +- Gate effect: {none | blocks final verdict until completed / user-approved downgrade} + +## 2. Design Summary + +- Goal: {摘要} +- Key contracts: {名词层 / 编排层摘要} +- Steps: {数量 + 风险热点} +- Checks: {数量 + 来源完整性} +- Baseline / validation: {摘要} + +## 3. Findings + +### blocking + +- [ ] FDR-001 `{path#section|checklist.step|file:line}` {问题} + - Evidence: {事实} + - Impact: {为什么阻塞用户 review / implement} + - Expected fix scope: {修复边界} + +### important + +- [ ] FDR-00N `{证据位置}` {问题} + - Evidence: {事实} + - Impact: {影响} + +### nit + +- [ ] FDR-00N `{证据位置}` {建议} + +### suggestion + +- [ ] FDR-00N {建议} + +### learning + +- {可复用设计经验或注意点} + +### praise + +- {值得保留的做法} + +## 4. User Review Focus + +- 用户需要重点拍板：{决策 / 假设 / 不做范围} +- implement 需要重点遵守：{契约 / steps / 验证} +- code review / QA / acceptance 需要重点复核：{风险 / 证据} + +## 5. Evidence Confidence Ledger + +| Check | Verdict | Evidence Class | Basis | Follow-up | +|---|---|---|---|---| +| Acceptance Coverage Matrix | pass|warn|fail | E|C|H | {路径 / 事实 / 判断依据} | {none / 复核点} | +| DoD Contract | pass|warn|fail | E|C|H | {依据} | {复核点} | +| Steps and checks traceability | pass|warn|fail | E|C|H | {依据} | {复核点} | +| Roadmap contract compliance | pass|warn|fail | E|C|H | {依据} | {复核点} | +| Module interface design | pass|warn|fail|n/a | E|C|H | {依据} | {复核点} | +| Validation and artifacts | pass|warn|fail | E|C|H | {依据} | {复核点} | + +Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。 + +## 6. Residual Risk + +- {风险 + 下游如何处理；没有写 none} + +## 7. Verdict + +- Status: passed|changes-requested|blocked +- Next: 交给用户整体 review | 回 `cs-feat` design 阶段 修订后重跑 `cs-feat` design-review 阶段 | 等独立 Task agent reviewer 完成 / 用户确认降级后重跑 +``` + +没有某类 finding 时写 `none`，不要删除章节；下一轮复审要能对比。 + +--- + +## 退出条件 + +- [ ] 已读取 attention、design、checklist、相关 intent / brainstorm / roadmap / req / arch / compound。 +- [ ] 已按 design 声明核验必要代码、接口、类型、组件或命令事实。 +- [ ] 已确认 checklist 可解析，steps/checks 都可追溯。 +- [ ] 已按 Task agent 选择规则启动独立 reviewer；若未启动，已记录确无能力 / provider 不可用 / 用户授权降级。 +- [ ] 如果启动了独立 Task agent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。 +- [ ] 已审查需求边界、术语、名词层、编排层、挂载点、结构健康度、验收契约、steps/checks、基线、交付物、清洁度。 +- [ ] 已检查 Acceptance Coverage Matrix、Feature Design Review Invariants 和 Evidence Confidence Ledger。 +- [ ] 核心检查 H-only 时没有静默 passed。 +- [ ] 已写 `.codestable/features/{feature}/{slug}-design-review.md`。 +- [ ] 有 blocking / 未处理 important 时指向 `cs-feat` design 阶段 修订并重跑 review。 +- [ ] 无 blocking 且 important 已处理或明确接受时，明确告诉用户下一步是 feature design 人工 review。 + +--- + +## 容易踩的坑 + +- 把 design review 做成文案润色，没审 steps/checks 是否能执行。 +- 只读 design，不核对 checklist 来源。 +- roadmap 起头时不检查接口契约，导致 feature 偷偷绕开 roadmap。 +- 现状段没读代码就放过，implement 阶段才发现设计站不住。 +- steps 出现"和 / 以及 / 同时"却不复查是否该拆。 +- 把批量 design 或赶时间当成 local-only 降级理由。 +- 启动独立 Task agent reviewer 后结果还没回来，就把本地 review 定稿为 passed。 +- 外部 reviewer 的结论没经本地事实核验就照抄。 +- review 报告没有落盘，导致用户 review 和后续实现没有可追溯输入。 diff --git a/plugins/codestable/skills/cs-feat/references/design/protocol.md b/plugins/codestable/skills/cs-feat/references/design/protocol.md new file mode 100644 index 0000000..d7f3f91 --- /dev/null +++ b/plugins/codestable/skills/cs-feat/references/design/protocol.md @@ -0,0 +1,272 @@ +# Feature Design Protocol + +这一阶段的产出是一份方案文件 `{slug}-design.md`，加上从中抽出的行动清单 `{slug}-checklist.yaml`，以及人审前的 `{slug}-design-review.md`。这些东西后面会被 implement / code review / QA / acceptance 消费，所以这里写错或写漏，下游就跟着错。 + +> 共享路径和命名约定看 `.codestable/reference/shared-conventions.md`。本阶段一般 feature 目录已经由 brainstorm 创建好了；没有的话在这一步建。 +> 报告语言：design / plan 正文必须按 `.codestable/attention.md` 用**中文**；若草稿用了英文，落盘前先改写为中文。frontmatter / yaml 字段不翻译。 + +本阶段有三个入口： + +- **正式起草**：用户已经能讲清楚需求（或已经填好 `{slug}-intent.md`），直接进"流程"一节走完整起草。 +- **初始化模式**：用户说"开一个新需求 / 起个草稿 / 新建一个 feature"，但想自己先写半成品方案而不是口述。走下一节"初始化模式"，建好目录和空 `{slug}-intent.md` 就结束本轮，等用户填完再回来。 +- **从 roadmap 条目起头**：用户说"开始做 roadmap 里的 {子 feature slug}"或"推进 {roadmap} 的下一条"。slug 从 roadmap items.yaml 取，不另起；动笔前要读 roadmap 主文档和 items.yaml 了解上下文和依赖状态；落盘时 frontmatter 要带 `roadmap` / `roadmap_item` 两个字段，同时回写 items.yaml 把对应条目 `status` 改为 `in-progress`、`feature` 填为 feature 目录名。详见下文"从 roadmap 条目起头"。 + +**设计原则**：design 不是实现前的散文说明，而是后续实现和验收的可执行契约。它必须把"做好"翻译成可观察证据，把 steps 切成独立可验证单元，把风险和依赖前置暴露，并在交给用户前做一次自我批判，修掉含糊标准、混合步骤和薄弱依赖。 + +**推进原则**：design 要把后续执行需要的"操作手册"写到位：当前基线怎么确认、每步完成后看什么证据、哪些命令必须重跑、哪些交付物要真实落盘、失败时回到哪个契约修。否则 implement 只能临场判断，review 没有稳定契约可审，QA 不知道该跑什么证据，acceptance 也只能相信实现汇报。 + +--- + +## 初始化模式：帮用户建目录和 intent 草稿 + +适用：用户想自己写一份半成品方案（`{slug}-intent.md`）作为后续 design 的输入，但不想手动建目录。 + +动作： + +1. **和用户快速对齐两件事**——一句话需求概要 + 敲定 slug（小写字母、数字、连字符；`user-auth`、`export-csv` 这种）。日期取当天（frontmatter 用 `currentDate` 即可）。feature 目录命名是 `YYYY-MM-DD-{slug}`。 +2. **创建 `.codestable/features/{YYYY-MM-DD}-{slug}/` 目录**。 +3. **写一份空的 `{slug}-intent.md`** 作为草稿骨架，模板见 `support/intent-template.md` + 的“feature intent 草稿模板”。 + +4. **告知用户"骨架已建好，填完后再来找我，我基于 intent 写正式 design"**，然后**本轮结束，不继续推进 design 流程**。 + +为什么在这里停？intent 的价值就是让用户离线思考、把脑子里的东西落到纸面。AI 继续问会把 intent 模式退化成 brainstorm，失去意义。 + +--- + +## 从 roadmap 条目起头 + +适用：用户说"开始做 roadmap 里的 {子 feature}"或指向 items.yaml 里某条 `planned` 条目。 + +1. **读 roadmap 上下文**——打开 `{roadmap-slug}-roadmap.md` 和 `{roadmap-slug}-items.yaml`： + - 目标条目必须 `status: planned` + `depends_on` 前置全 `done`，否则停下来报告 + - **必读主文档第 3 节"模块拆分"和第 4 节"接口契约 / 共享协议"**——这是本 feature 的硬约束输入。契约不合理 / 漏了 → 停下来建议回 `cs-epic` planning/update 改，**不要在 design 里偷偷绕开** +2. **slug 从 roadmap 取**，feature 目录 `YYYY-MM-DD-{roadmap 条目 slug}`，不另起 +3. **走"流程"一节**，frontmatter 加 `roadmap` / `roadmap_item` 两字段 +4. **候选落盘时回写 items.yaml**：对应条目 `status: in-progress` + `feature: YYYY-MM-DD-{slug}`，用 `validate-yaml.py` 校验；design 先保持 `status: draft`，通过 `cs-feat` design-review 阶段 且用户确认后才改 `approved` + +完整衔接协议看 `.codestable/reference/shared-conventions.md` 第 2.5 节。 + +--- + +## design 写什么、不写什么 + +design 只管"编排-计算分离"里的编排那一侧：**这次 feature 在名词层和编排层的现状与变化**。计算层细节（具体怎么写、改哪些函数、测试怎么搭）归 implement。 + +写三类东西，名词层和编排层都用"**现状 → 变化**"两段式： + +1. **名词层**——值对象 / 实体 / 数据结构 / 对外契约 / 类型定义 +2. **编排层**——主流程 / workflow / 关键编排函数 / 控制流拓扑（线性 / 分支 / 并行 DAG / 状态机）。开头一张主流程图建 mental model +3. **流程级约束**——错误语义、幂等性、并发 / 顺序、扩展点位置、可观测点。挂载点清单也归这类 + +当本 feature 引入或改变 module interface、seam、adapter、跨依赖测试策略时，按 `support/codebase-design.md` 做内嵌 deep-module 检查；这不是切换到独立 `codebase-design` skill。 + +外加一个**固定结构健康度环节**（第 2.5 节）：评估即将被改动的文件是否偏胖 / 职责混杂、以及新文件要落进的目录是否摊平，决定是否在实现前先做"只搬不改行为"的微重构（拆文件 / 重组目录）。即使结论是"不做"也要在 design 里显式写出来——否则 AI 默认会持续往胖文件里塞代码、往拥挤目录里加文件。这一节随整稿一起进整体 review，不单独走确认。 + +**判据**：换一种写法名词层或编排层会变得不同 → design 的事；换一种写法只是"代码不那么好看 / 函数拆法不同 / 测试用了别的 framework" → implement 的事。 + +不写改动文件清单、函数级落点、测试代码、库选型细节——design 阶段还没读完相关代码，预测多半会回头改。implement 拿到 design 后才扫现状决定。 + +--- + +## 方案文件是给人概览的，不是给人仔细阅读的 + +读者打开 `{slug}-design.md` 是想 5 分钟内抓到要点，不是逐字精读。具体做法： + +1. **每节超过 1 屏就砍或拆**——一屏装不下读者会失去定位 +2. **术语先锁死**——动笔前 grep 代码 / 架构 / 历史 feature 防冲突，事后理顺成本远高于预防 +3. **示例优先于定义**——接口行为先给"输入→输出"示例，复杂时再补正式类型 +4. **同一条信息只在最自然的位置出现一次**——重复表述比缺一条还烦 +5. **新逻辑默认放新文件**（写在改动计划里）——文件越大越难分清职责 + +--- + +## 起草时的三条纪律 + +### 1. 别替用户做决定 + +碰到"用户没说清的角落"默认停下来问，不自己挑一个填上去。具体： + +- **声明假设**：非用户原话的判断写成"假设：……"，让用户能精确反驳 +- **给选项不自选**：2-3 种合理做法都摆出来再讲倾向 +- **看不懂就停**：硬猜着写下去到了 acceptance 阶段对不上验收点 + +### 2. 目标和约束都写成可验证的 + +- 不写"让它能跑"、"用户体验顺畅"这种弱标准——改写成"输入 A 时返回 B" +- "明确不做"具体到能被 grep 或测试反向核对，不写"不过度设计"这种空话 + +### 3. 每个 feature 都要能被卸载 + +回答："如果想把它拔掉，要拔哪些地方？" 答不出说明边界没想清楚，feature 一上线就变成拆不动的既成事实。 + +落到挂载点清单（第 2.3 节）。**判据**：删掉这一项，feature 在用户/系统视角是不是就消失了？是→列，否→不列。详细 ✅/❌ 例子和写法看 reference.md。这清单顺带帮你发现自己有没有不小心往太多地方插桩——真挂入点越多代表耦合越散，是个信号。 + +--- + +## 流程：什么时候做什么 + +### 1. 启动检查 + +**前置 gate**：需求输入至少含 用户目标 / 核心行为 / 成功标准 / 明确不做 四项（来源 intent / brainstorm / 对话）。缺了补；用户自己说不清就回退到 brainstorm。 + +**必做 4 条**： + +1. **续作检查**——Glob `{slug}-design.md` / `{slug}-intent.md` / `{slug}-brainstorm.md`： + - intent / brainstorm：当作输入读入，不重复问已讲清的部分 + - design `status=draft` 各节基本完整 → 若 checklist 存在则跳到本流程"5. 独立 design review gate"，否则先生成 checklist + - design 部分节缺失 → 补缺失节，汇报"上次写到 X，补齐统一给你 review" + - design `status=approved` → 别默认覆盖，问用户接着改还是另起 slug +2. **扫 .codestable/ 全局输入**——Glob `.codestable/` 发现可用目录和文档类型，按类取用： + - `requirements/CONTEXT.md` → 读领域术语表，用项目术语命名，不自己造名 + - `requirements/adrs/` → 跨模块或流程级约束相关的 ADR 必读；命中和方案冲突的 ADR **必须**正面回应"为什么仍然这么做"或调整方案 + - `requirements/{slug}.md` → 有对应 req：frontmatter `requirement` 填 slug，读"用户故事 / 边界"两节；新能力首次出现 → 触发 `cs-req draft` 起草愿景 req，frontmatter `requirement` 填新 slug；纯重构 / 技术债留空 + - `compound/` → `grep -r "关键词" .codestable/compound/` 搜历史沉淀；命中相关坑点 / 写法约束就融进方案 + - `features/` → 搜历史 design 有无同类 feature 可参考 + - 其余目录按内容类型自行判断 +3. **读需求相关的现有代码**——读哪些文件由需求线索决定 +4. **识别验证基线**——从 attention / README / package scripts / CI / 历史 acceptance 里找本 feature 应用的 build / typecheck / lint / test / e2e / 浏览器验证入口；如果命令当前可能已红，写入第 1 节"基线风险"，implement 开始前要先做轻量预检，避免把既有红灯误算成本 feature 失败 + +**按信号触发 3 条**（没信号跳过）： + +- **术语 grep 防冲突**——新概念名没在代码 / 架构 / 历史 feature 里见过时，grep 一遍；冲突就换名或在第 0 节明确区分 +- **复杂度档位对齐**——需求里出现"对外 SDK / 高并发 / 一次性工具"等偏离信号时，打开 `.codestable/reference/code-dimensions.md` 列偏离点；无信号写"走默认档位" +- **grep 找"叫法不同的类似模块"**——直觉"可能已有人做过但命名不同"时，grep 同义词 + +详细规则看 `.codestable/reference/shared-conventions.md` 第 5 节。 + +### 2. 想清楚这功能该放在哪儿 + +动笔写名词层 / 编排层前，先回答：**这次要加的东西在项目整体结构里属于哪儿？** + +- 现有模块本该承担？→ 在那个模块里扩展，别另起 +- 横跨多个模块？→ 抽公共层 vs 让某一方主导、其他方依赖 +- 跟现有任何模块都不像？→ 新建独立模块/子系统，对外暴露什么、跟别人怎么交互提前想清楚 +- 可能已有模块在做类似的事但叫法不同？→ grep 几个同义词 + +代价：放错了模块就变"什么都装的筐"；新建平行实现就有几个版本同存。 + +结论写进第 1 节"决策与约束"。涉及新建模块或跨模块接口时，提示用户走 `cs-domain` 起一条 ADR 记下这个结构性决策。 + +AI 默认翻车的姿势是**不思考就往眼前最顺手的文件里加**。 + +### 3. 写"现状 → 变化"两段式的名词层和编排层 + +按 reference.md 模板写第 2 节四个子节（2.1 名词层 / 2.2 编排层 / 2.3 挂载点 / 2.4 推进策略）。重点提示： + +- "现状"必须指向代码位置，不能想当然——读者要靠它判断"变化"是否合理 +- 触碰 module interface / seam / adapter 时，补 `support/codebase-design.md` 里的 Interface 设计检查 +- 编排层开头一张 mermaid 图建 mental model +- 挂载点按"删了它 feature 是否消失"判据，3-5 条为正常区间 +- 推进策略按 paradigm 维度切片（编排骨架 → 计算节点 → 持久化 → 测试），不下沉到 file:line +- **第 2.5 节"结构健康度与微重构"是固定步骤**——按 reference.md 写作要求评估**两类对象**：要改的文件（文件级）+ 要落新文件的目标目录（目录级）。**评估前先查 compound 已有 convention**（关键词围绕"目录组织 / 文件归属 / 命名约定"），命中就直接照办。结论三选一： + 1. **不做**——文件健康 / 目录不挤 / 改动量小 / 微重构收益不抵风险，写"本次不做微重构，原因：……" + 2. **做微重构（拆文件）**——文件偏胖或职责混杂但能用 provable refactor（拆函数 / 拆文件 / 移动定义，编译器全程绿灯）解决 + 3. **做微重构（重组目录）**——目标目录摊平且能通过纯文件移动 + import 路径更新解决（编译器全程绿灯） + + 选择 2 / 3 时给出"搬什么 → 搬到哪 → 怎么验证行为不变"的具体方案，落进 checklist 作为**第 1 步且独立验证退出**，再开始 feature 主体 +- **重组目录时多问一步：是稳定模式还是一次性整理**——稳定模式（如"自定义业务组件统一放 `components/custom/`"，未来其他 feature 也该遵守）就在 2.5 末尾加"建议沉淀的 convention"段，提示用户 implement 跑通后走 `cs-keep` 归档；一次性整理（只是这个目录碰巧挤了）就只搬不归档。**design 阶段不直接归档**——方案还没真跑过，留钩子给 implement 后再决定 +- **design 只做安全的微重构，边界严格守住**："只搬不改行为"——文件级靠 IDE rename / move + 编译器校验，目录级靠纯文件移动 + import 路径更新 + 编译器校验。一旦涉及改函数签名 / 改返回值结构 / 改调用关系语义 / 模块拆合，就**超出 design 范围**：写进第 2.5 节末尾的"超出范围的观察"里提示用户"建议后续走 `cs-refactor` 处理"，**不阻塞本 feature、不作为前置依赖**。是否真去做、什么时候做由用户在 feature 之外决定 +- **第 2.5 节随整稿一起 review，不单独确认**——和功能方案打包给用户一次过，避免拆成两轮把节奏拖长 + +### 4. 补齐剩下各节，生成 review candidate + +按 reference.md 模板补齐剩余节（第 0 / 3 / 4 节）。初稿 frontmatter `status: draft`。 + +整稿成型后先确认正文语言符合 `.codestable/attention.md`（默认中文；英文草稿先改写），再落盘 draft design，并从 `{slug}-design.md` 抽出 candidate `{slug}-checklist.yaml`。checklist 的 steps/checks 初始都保持 `pending`，用 `validate-yaml.py` 校验。不要等用户确认后才生成 checklist，因为人审前的 `cs-feat` design-review 阶段 需要同时审 design 和 checklist 是否对齐。 + +第 3 节"验收契约"提示：每条写成"输入 / 触发 → 期望可观察结果"，覆盖正常 + 边界 + 错误，并补 `Acceptance Coverage Matrix` 和 `DoD Contract`；完整模板看 reference.md。 + +**补一段执行风险与证据计划**（写进第 1 节或第 2.4 节，按文档自然位置放）： + +- **Top 3 风险**：最可能实现偏、最难回滚、最容易验收遗漏的三点；每点写对应缓解（某个 step、某条验收场景、某个先验命令） +- **非显然依赖**：外部服务、数据迁移、现有模块顺序、用户拍板项；说明阻塞哪个 step +- **证据类型**：每个验收场景最终靠什么证明（类型 / 单测 / 集成 / 手工 / 浏览器截图 / API 响应 / diff review） +- **关键假设**：不是用户原话但方案依赖它成立的判断，review 时让用户能改 +- **必跑验证命令**：本 feature 完成前必须运行哪些命令；命令可能基线已红时写清"预检先跑，红灯要分清既有问题 / 本次引入" +- **交付物清单**：最终应该新增 / 修改 / 删除的用户可见或系统可见产物类别（代码入口、配置 key、schema、路由、文档归并、roadmap 状态），acceptance 要按仓库事实反查 +- **清洁度规则**：本 feature 不允许新增的调试输出、临时 TODO/FIXME、注释掉代码、无用 import；如某类 debug 输出是功能本身，必须在 design 里显式说明例外和范围 + +**steps 写法原则**： + +- 步数由工作自然切片决定，不为了凑 4-8 合并不相干内容；如果确实超过 8，先检查是不是应该退回 roadmap 拆子 feature +- 每步交付一件 coherent thing，能独立验证；名字里出现"和 / 以及 / 同时"时复查是否该拆 +- 每步 `exit_signal` 必须是 yes/no，可由命令、测试、截图、接口响应、页面观察、类型检查或 diff review 证明 +- 每步要标出建议验证动作（命令 / 手工 / 浏览器 / diff review）和主要交付物类型，方便 implement 做 step 证据块 +- UI feature 最后必须覆盖可见状态与 polish：空态、加载、错误、禁用 / 未授权、长文本 / 小屏、focus / keyboard / contrast；如果不适用写明原因 +- 涉及安全 / 权限 / 输入处理 / 数据迁移时，最后一个功能 step 或单独 step 必须覆盖 harden：校验、越权、回滚、兼容、回归面 + +**交给用户前做一次自我批判**，并先在文档里修掉问题： + +1. **可证伪性**：第 3 节和 checklist 的每条是不是 yes/no？有没有"正常 / 完善 / 友好 / 稳定"这种无法核对的词？ +2. **步骤原子性**：有没有一个 step 塞了两件可以独立验收的事？有没有 step 只有下一步完成后才有意义？ +3. **最弱依赖**：哪个 step 出错会污染后续最多内容？是否需要提前验证、拆成独立 step、或补验收场景？ +4. **证据完整性**：每条关键场景是否都有证据类型？前端是否需要浏览器截图 / 肉眼验证？ +5. **基线可执行性**：必跑命令是否明确？如果命令当前可能已红，是否有预检和归因说明？ +6. **交付物可核验性**：acceptance 是否能从 git diff / 文件系统 / 配置 / 文档状态看到每个承诺产物？ +7. **清洁度覆盖**：是否明确禁止临时调试输出、TODO、死 import、注释掉代码，并说明必要例外？ +8. **接口深度**：新增 / 改动的 interface 是否给 caller 足够 leverage？seam 和 adapter 是否真实需要？ + +### 5. 独立 design review gate + +运行 `cs-feat` design-review 阶段： + +- `passed`：才能把 design + checklist + design-review 报告交给用户整体 review。 +- `changes-requested`：按 finding 修 design/checklist，重新校验 yaml 并重跑 `cs-feat` design-review 阶段。 +- `blocked`：补齐输入、等待独立 Task agent reviewer，或让用户明确降级 local-only 后重跑。 + +### 6. 用户整体 review + +发一次整体 review 提示（提示词在 reference.md 第 5 节），同时附上 Top 3 风险、关键假设、自我批判结论和 `{slug}-design-review.md` 摘要。用户提意见就改；如果修改影响名词层、编排层、验收契约、steps/checks、roadmap 契约或风险策略，必须同步更新 checklist 并回到 Phase 5 重跑 design review。用户明确放行后，把 `status` 从 `draft` 改 `approved`。 + +### 7. 确认 checklist + +确认 `{slug}-checklist.yaml` 已与最终 approved design 同步。完整格式、提取规则、典型节奏看 reference.md 第 3 节。 + +落盘后 `python .codestable/tools/validate-yaml.py --file {path} --yaml-only` 校验。 + +### 8. 退出 + +按下文退出条件核对，引导用户进入阶段 2。 + +--- + +## 退出条件 + +用户整体 review 通过，并且： + +- [ ] frontmatter 完整（`doc_type` / `feature` / `status=approved` / `summary` / `tags`），requirement 字段已对齐 +- [ ] design 正文已按 `.codestable/attention.md` 的报告语言落盘（默认中文；frontmatter / yaml 字段保持机读格式） +- [ ] 第 1 节含"不做什么"和复杂度档位偏离（或明确走默认） +- [ ] 第 2.1 / 2.2 用"现状 → 变化"两段式；接口有示例 + 来源位置；编排层开头有主流程图 +- [ ] 触碰 module interface / seam / adapter 时，已记录 depth / locality / seam / dependency strategy 检查结论 +- [ ] 第 2.3 挂载点按"删了它 feature 是否消失"判据收紧（一般 3-5 条） +- [ ] 第 2.4 推进策略按 paradigm 维度切片，每步有退出信号 +- [ ] 第 2.5 结构健康度评估覆盖文件级 + 目录级；评估前已查 compound convention；结论显式写出（不做 / 拆文件 / 重组目录）；选"微重构"时 checklist 第 1 步是它且有独立退出信号；选"重组目录"且属稳定模式时含"建议沉淀的 convention"段；超出"只搬不改行为"的结构性问题列在"超出范围的观察"，仅提示不阻塞 +- [ ] 第 3 节关键场景覆盖正常 + 边界 + 错误；含"明确不做"反向核对项；每条都有证据类型、Acceptance Coverage Matrix 和 DoD Contract +- [ ] Top 3 风险 / 非显然依赖 / 关键假设已写入 design 或 review 摘要 +- [ ] checklist steps 每步都能独立验证，exit_signal 是 yes/no；UI / 安全 / 迁移类 feature 已覆盖 polish / harden 或写明不适用 +- [ ] 已做可证伪性 / 步骤原子性 / 最弱依赖 / 证据完整性自我批判并修正问题 +- [ ] 必跑验证命令 / 基线风险 / 预检要求已写清 +- [ ] 交付物清单可被 acceptance 从仓库事实核验 +- [ ] 清洁度规则已写清：调试输出、临时 TODO/FIXME、注释掉代码、无用 import 的处理口径明确 +- [ ] `{slug}-design-review.md` 已通过 `cs-feat` design-review 阶段，没有 unresolved blocking finding +- [ ] `{slug}-checklist.yaml` 已落盘并通过 `validate-yaml.py` 校验 +- [ ] roadmap 起头时 items.yaml 已回写（`status: in-progress` + `feature` 填上） + +--- + +## 容易踩的坑 + +- 没读相关架构 / 术语没 grep 就动笔——方案跟现有代码对不上、术语冲突后 git blame 找十倍时间 +- 用散文描述接口行为，没给具体示例——读者建不起模型 +- 名词层 / 编排层只写"变化"不写"现状"——读者无法判断变化是否合理 +- 把挂载点清单写成改动文件清单——内部改动归 implement，挂载点只列"删了它 feature 就消失"的登记条目 +- 在 design 写测试代码 / framework / mock / 函数级落点——这些归 implement 自决 +- 接口只写签名不写 invariant / ordering / error mode / seam rationale——implement 和测试会各自补语义 +- 强行画图——模块 ≤ 2 个、调用线性时画图反而模糊重点 +- 只给半份文档先 review——用户看不出全局一致性 +- 跳过 `cs-feat` design-review 阶段 直接让用户拍板——用户只能看到方案表面，看不到 checklist、契约、验收策略的独立审查结论 +- 在需求摘要里偷偷扩范围——验收时对不上 +- 验收场景写成"体验良好 / 状态完整 / 逻辑正确"——acceptance 无法判定，只能靠感觉 +- checklist step 只有下一步完成后才能验证——说明切片不独立，执行中失败时无法定位 diff --git a/plugins/codestable/skills/cs-feat-design/reference.md b/plugins/codestable/skills/cs-feat/references/design/reference.md similarity index 97% rename from plugins/codestable/skills/cs-feat-design/reference.md rename to plugins/codestable/skills/cs-feat/references/design/reference.md index e442620..7b54f80 100644 --- a/plugins/codestable/skills/cs-feat-design/reference.md +++ b/plugins/codestable/skills/cs-feat/references/design/reference.md @@ -1,6 +1,6 @@ # feature-design 参考模板 -本文件提供 `cs-feat-design` 使用的 `{slug}-design.md` / `{slug}-checklist.yaml` 参考格式。 +本文件提供 `cs-feat` design 阶段 使用的 `{slug}-design.md` / `{slug}-checklist.yaml` 参考格式。 ## 1. {slug}-design.md frontmatter @@ -52,7 +52,7 @@ checks: status: pending ``` -`steps`（design draft 成型后先产出，供 `cs-feat-design-review` 和用户 review；用户确认后随 design 一起进入实现）： +`steps`（design draft 成型后先产出，供 `cs-feat` design-review 阶段 和用户 review；用户确认后随 design 一起进入实现）： - 粒度是 paradigm 维度，**不写 file:line / 函数级**——具体落点是 implement 的事 - 切片顺序"最简 Workflow 先行 → 逐个节点填充"： @@ -111,7 +111,7 @@ design 的灵魂。**所有子节用"现状 → 变化"两段式**——不写" - 后端 API：输入 → 输出，含正常 + 主要错误路径 - 前端组件：组件拆分（父子关系 + 拆分理由）、Props / Events / Slots 用示例说明、状态归属（组件内部 / props / store） - 示例下注释标来源：`// 来源：{文件路径} {函数名 / 组件名}` -- **Interface 设计检查**：涉及 module interface / seam / adapter 时，按 `references/codebase-design.md` 补 module、interface facts、seam、depth / locality、dependency category 和 adapter 结论。 +- **Interface 设计检查**：涉及 module interface / seam / adapter 时，按 `support/codebase-design.md` 补 module、interface facts、seam、depth / locality、dependency category 和 adapter 结论。 #### 2.2 编排层：主流程与控制流 @@ -284,4 +284,4 @@ Required Artifacts: {review / QA / acceptance / evidence pack / screenshots / co > > 有修改意见直接说，确认后进入实现阶段。 -> 人工 review 前必须先有 `{slug}-design-review.md` 且 `status: passed`。用户修改 design/checklist 后，实质变化要重跑 `cs-feat-design-review`。 +> 人工 review 前必须先有 `{slug}-design-review.md` 且 `status: passed`。用户修改 design/checklist 后，实质变化要重跑 `cs-feat` design-review 阶段。 diff --git a/plugins/codestable/skills/cs-feat-design/references/codebase-design.md b/plugins/codestable/skills/cs-feat/references/design/support/codebase-design.md similarity index 94% rename from plugins/codestable/skills/cs-feat-design/references/codebase-design.md rename to plugins/codestable/skills/cs-feat/references/design/support/codebase-design.md index 62843e0..3eb3044 100644 --- a/plugins/codestable/skills/cs-feat-design/references/codebase-design.md +++ b/plugins/codestable/skills/cs-feat/references/design/support/codebase-design.md @@ -1,6 +1,6 @@ # Feature Design 内嵌 Codebase Design 检查 -这份 reference 是 `cs-feat-design` 的内嵌设计检查，不是独立 skill 入口。不要切换到全局 `codebase-design` skill；只在当前 feature design 里补强 module interface 质量。 +本文件是 `cs-feat` design 阶段的内嵌设计检查清单。只在当前 feature design 里补强 module interface 质量，不切换到全局 `codebase-design` skill。 ## 什么时候用 diff --git a/plugins/codestable/skills/cs-feat-design/references/intent-template.md b/plugins/codestable/skills/cs-feat/references/design/support/intent-template.md similarity index 77% rename from plugins/codestable/skills/cs-feat-design/references/intent-template.md rename to plugins/codestable/skills/cs-feat/references/design/support/intent-template.md index e72d3fa..abcd036 100644 --- a/plugins/codestable/skills/cs-feat-design/references/intent-template.md +++ b/plugins/codestable/skills/cs-feat/references/design/support/intent-template.md @@ -1,6 +1,6 @@ # feature intent 草稿模板 -`cs-feat-design` 初始化模式使用本模板创建 `{slug}-intent.md`。创建后本轮结束，等用户填完再回到正式 design。 +`cs-feat` design 阶段 初始化模式使用本模板创建 `{slug}-intent.md`。创建后本轮结束，等用户填完再回到正式 design。 ```markdown --- diff --git a/plugins/codestable/skills/cs-feat/references/fastforward/protocol.md b/plugins/codestable/skills/cs-feat/references/fastforward/protocol.md new file mode 100644 index 0000000..edf63d3 --- /dev/null +++ b/plugins/codestable/skills/cs-feat/references/fastforward/protocol.md @@ -0,0 +1,214 @@ +# Feature Fastforward Protocol + +用户让你做小功能时本来 AI 就会直接动手——这个技能**不改变这件事**。它只做一件事：动手前把项目里已沉淀的 CodeStable 知识指给你，按需搜一下，写出来的代码就比裸写多一层保护；动手后回写一份**最简的 `{slug}-ff-note.md`** 让这次工作可追溯、可被 cs-req / cs-domain backfill 看到、能纳入 scoped-commit 提交。 + +很轻：没有 design doc / checklist / 验收清单 / 动手前的用户确认。看完指引，该读代码读、该写代码写、写完回写一段话。 + +--- + +## 动手前先扫一眼 .codestable/ + +Glob `.codestable/` 发现可用目录和文档，按需取用： + +- **`requirements/CONTEXT.md`** — 领域术语；用项目术语命名，不自己造名 +- **`requirements/adrs/`** — 已拍板的架构决策；改跨模块的东西前 grep 相关 adr 避免违反 +- **`compound/`** — 沉淀的坑点 / 技巧 / 调研： + ```bash + grep -r "关键词" .codestable/compound/ + ``` +- **`requirements/{slug}.md`** — 有相关 req 时读边界 +- **`features/`** — 有同类 feature 时参考其 design +- **`reference/`** — shared-conventions.md / tools.md + +--- + +## 怎么用 + +动手前问 2 个问题： + +1. **这块代码以前有人栽过跟头吗？** → `grep -r "关键词" .codestable/compound/` +2. **这块代码有没有已经拍板的写法约束？** → 看 `requirements/adrs/` 相关 ADR + grep `compound/` 找写法沉淀 + +命中就把结论融进实现（**按约束来写**，不是抄）。没命中按自己判断写很正常。搜不到换几个关键词再试。 + +--- + +## 执行 gate（worktree + commit） + +fastforward 直接改项目源码且是快速通道末端，两道 gate 仍要走。slug 未定时先按动作敲定（见下文"自动生成 slug"），unit 路径用 `.codestable/features/YYYY-MM-DD-{slug}`。 + +动手前运行 start gate： + +```bash +python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/features/YYYY-MM-DD-{slug} +``` + +gate 不通过就不要开始改代码；用户批准 override 时先在 unit 目录写 `worktree-override.md`（reason / scope / approval）。 + +ff-note 落盘、收尾提交前运行 commit gate： + +```bash +python3 .codestable/tools/codestable-worktree-gate.py --root . --json commit --unit .codestable/features/YYYY-MM-DD-{slug} +``` + +gate 不通过就先处理 findings，不把"验证已过"当成完成。gate 工具的安装与 branch-guard hook 说明见 `.codestable/reference/branch-guard-hooks.md`。 + +--- + +## 写代码时守住这几条 + +design / implement 的硬约束在 fastforward 的精简版。没 design doc 不代表可以不讲——这些是让你"直接动手"时不偏向 AI 默认会踩的坑。 + +先做 `.codestable/reference/shared-conventions.md` 第 7 节的**第一性原则 pre-pass**：外部行为、不可破约束、最小充分改动、必须不写的东西。下面每条都用这四项压住发散。 + +### 先想"放在哪儿"再写 + +30 秒回答：**这次要加的东西在项目结构里属于哪儿？** + +- 现有模块本该承担？→ 在那扩展，别另起 +- 横跨多个模块？→ 抽公共层 / 让某一方主导 +- 已有模块叫法不同？→ grep 同义词 +- 跟现有都不像？→ 多半该切回完整 design 流程 + +默认坑：**不思考就往眼前最顺手的文件里加**——加完就成"什么都装的筐"。 + +### 扫一眼要改的文件现在什么状况 + +开写前看一眼：文件多长？承担几件事？类有多少方法？新加的是自然扩展还是把它推向"什么都能干"？ + +健康就直接加；要先收拾（拆长文件 / 抽重函数）就**先收拾再加**，范围锁死为"只搬不改行为"；结构性问题（职责重划 / 模块拆合）→ 停下来回 design 流程。 + +### 默认写最少的代码 + +只写用户明确要的。不顺手加： + +- "以后可能要"的配置项 / 参数开关 / 抽象层 / 接口 / 工厂 +- 没人要的防御性兜底 / try-catch +- 用户没提的边界处理 + +判据：写完觉得"是不是还得加点 X"——X 是不是用户能感知到的？不是就别加。多出来的代码不是中性的，是后人维护的负担。 + +### 只动该动的 + +只改要改的函数。同文件里别的函数丑 / 命名怪——**除非和这次冲突，否则别碰**。新代码风格匹配当前文件已有写法。看到值得改的别处 → "顺手发现：{文件:行号} {问题}，不在本次范围"让用户决定。 + +### 新逻辑默认放新文件 + +会被其他地方引用 → 新文件；只一处用的小工具函数 → 就近放。 + +### 不打补丁分支 + +冒出 `if (特殊情况) { 特殊处理 }` → **停**。这种分支基本只因为思路没覆盖到这种情况，硬写下去得到的是"为让代码能跑而加的特殊逻辑"。要么改数据结构让它不需要特殊处理，要么明确承认是边界情况并注释说明为什么特殊。 + +### 反射信号触发就停 + +- 往 > 300 行文件追加 / 往 > 10 个方法的类加方法 +- 函数做的事越来越多超过一屏 +- 写第二段"跟上面那段基本一样改了两个变量"的代码 +- 函数参数加到第 4 个 +- 往 `utils.ts` / `helpers.ts` 万能 util 堆东西 +- 新起概念名时先 grep 同名 / 近义命名 + +完整清单看 `.codestable/reference/shared-conventions.md` 第 7 节。 + +--- + +## 写完回写 `{slug}-ff-note.md` + +代码写完、验证完、用户确认效果 OK **之后**才动这一步——动手前先建空壳会破坏 ff 的轻体感。 + +### 自动生成 slug + +不问用户。规则： + +- 从用户最初的请求里抽 2-4 个英文 kebab-case 词概括动作 / 对象（如 "rename-cwd-helper"、"add-export-button"、"fix-toolbar-layout"） +- 不抽业务名词缩写、不音译中文、保持小写连字符 +- 拿不准就保守一点："tweak-{对象}" / "small-{动作}" 也比强求精准好 + +最终路径：`.codestable/features/YYYY-MM-DD-{slug}/{slug}-ff-note.md`，日期用今天。 + +### 模板 + +```markdown +--- +doc_type: feature-ff-note +feature: {slug} +date: YYYY-MM-DD +requirement: {req-slug 或留空} +tags: [...] +--- + +## 做了什么 +{1-3 句：解决什么需求 / 加了什么能力，业务视角} + +## 改了哪些 +- {file:行号区间或函数名} — {一句话说改了什么} +- ... + +## 怎么验证的 +{1-2 句：跑了哪些验证 / 浏览器走通了哪条路径 / 跑了什么测试} + +## 顺手发现（可选，不阻塞） +- {文件:行号} {问题简述} — 不在本次范围 +``` + +**写得真的轻**：每节就那么几行，不要把它写成迷你 design / 迷你 acceptance。这份文档的目标是"半年后有人看 git log 能跳进来 30 秒搞清楚做了啥"，不是替代标准流程。 + +落盘后告诉用户："已写 `{slug}-ff-note.md`，本次 fastforward 闭环。" + +--- + +## 不做什么 + +- **不写 design doc / checklist / acceptance**——这就是 fastforward 的意义。要写就去 `cs-feat` design 阶段 +- **不跟用户确认方案**——用户让你做小功能就是不想等你开会 +- **不在 `.codestable/` 里留 `{slug}-ff-note.md` 之外的新文件**——除非发现值得沉淀的坑 / 技巧，另起对话用 `cs-keep` 写 + +--- + +## 什么时候跳出 fastforward + +干到一半发现下面任一情况，**停下来告诉用户"这比想象的复杂，建议切回完整流程"**： + +- 改动涉及 3 个以上子系统 +- 需要引入新术语或和现有术语冲突 +- 要打破 `.codestable/requirements/adrs/` 既定的模块边界 ADR +- 用户追加的要求让范围翻倍 + +切回方式：进入 `cs-feat` design 阶段。已写的代码在 design 里标"已部分实现"即可。 + +--- + +## 退出条件 + +- [ ] 代码写完且用户确认效果 OK +- [ ] `{slug}-ff-note.md` 已落盘且四节填齐（顺手发现可省） +- [ ] 没有未对齐的"顺手发现"（都进 ff-note 末节，留给后续） + +--- + +## 收尾提交 + +按 `.codestable/reference/shared-conventions.md` 第 4 节"scoped-commit"规则执行。本通道： + +- **提交范围**：本次代码改动 + `{slug}-ff-note.md` +- ff-note 落盘后告诉用户"已就绪，是否代为 commit？"，用户明确同意才执行 + +收尾 commit 前先进入 `cs-code-review` 做一轮独立 diff 评审，Critical / Important 未清零不进 commit；scoped-commit 发起权归 `cs-code-review`。 + +按 `shared-conventions.md` 第 3 节"feature-ff"收尾推荐顺序逐项一句话提示（用户"不用"立即跳过）： + +1. 暴露的坑或拍板的长期约束 → "沉淀到 compound？（`cs-keep`）" +2. 最后问是否代为 scoped-commit + +--- + +## 容易踩的坑 + +- 完全跳过知识检索就写——这个技能的唯一理由就是让你搜一下再写 +- 把搜到的 learning / decision 当"参考"而不是"约束"——decision 拍过板，违反要么重新 decision 要么别做 +- 开始写 design doc——fastforward 就是不写 design +- 发现任务变复杂还硬在 fastforward 推——切回成本远低于带着错误方案改到底 +- **动手前就建 ff-note 空壳**——破坏 fastforward 的轻体感，必须代码 + 验证完才回写 +- **把 ff-note 写成迷你 design / 迷你 acceptance**——四节加一起十几行就够，多了说明这事不该走 fastforward +- **跳过 ff-note 直接 commit**——和 issue-ff 强制 fix-note 同样的理由：没记录后人追溯不了 diff --git a/plugins/codestable/skills/cs-feat/references/implementation/protocol.md b/plugins/codestable/skills/cs-feat/references/implementation/protocol.md new file mode 100644 index 0000000..387e7f2 --- /dev/null +++ b/plugins/codestable/skills/cs-feat/references/implementation/protocol.md @@ -0,0 +1,287 @@ +# Feature Implementation Protocol + +到这一步用户已经在方案上签过字了，你的活是把方案变成代码。容易出问题的不是写代码本身，而是**实现路上发现方案没覆盖到的情况时怎么办**——硬冲下去就把方案当摆设了。下面整套规则就是为了让"停下来"成为默认动作。 + +**执行原则**：实现不是"一口气改完再说"，而是按已批准 checklist 做可验证增量。每一步要先明确退出信号，做完立刻拿证据验证；失败先诊断和重试，仍失败再写窄范围修复说明；连续失败才交还用户。不要让未验证的中间状态滚进下一步。 + +**推进原则**：实现阶段要让任务随时可恢复、可归因、可审计。开始前先确认基线；每步完成就更新 checklist 和证据；失败只修当前失败标准；每步都检查清洁度；遇到用户中断就在 step 边界停；学到会影响后续 feature 的知识先记录为候选，交给 acceptance 收尾沉淀。 + +> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md` 第 0 节。 + +--- + +## 执行 gate（worktree + commit） + +进入实现前运行 start gate，路径用项目运行时 `.codestable/tools/...`： + +```bash +python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/features/YYYY-MM-DD-{slug} +``` + +gate 不通过就不要开始改代码；用户批准 override 时先在 unit 目录写 `worktree-override.md`（reason / scope / approval）。 + +dogfood / 临时隔离仓库例外：只有当用户任务明确要求在一次性隔离 repo 里真实执行 workflow，且该 repo 不是交付目标主仓库时，允许不创建 linked worktree；仍必须在 unit 目录写 `worktree-override.md`，记录 `reason=dogfood-ephemeral-repo`、用户授权原文、影响范围和后续清理策略。不能把这个例外用于普通 feature 实现。 + +实现完成、输出汇报前运行 commit gate： + +```bash +python3 .codestable/tools/codestable-worktree-gate.py --root . --json commit --unit .codestable/features/YYYY-MM-DD-{slug} +``` + +gate 不通过就先处理 findings，不把"测试已过"当成完成。gate 工具的安装与 branch-guard hook 说明见 `.codestable/reference/branch-guard-hooks.md`。 + +--- + +## 写代码时的三条姿态 + +先做 `.codestable/reference/shared-conventions.md` 第 7 节的**第一性原则 pre-pass**：明确外部行为、不可破约束、最小充分改动和必须不写的东西。具体规则是这三条姿态的落点，理解姿态比记规则重要。 + +### 1. 默认写最少的代码 + +只写当前步骤明确要的东西。不顺手加"以后可能要"的可配置项、抽象层、参数开关、防御性兜底。判据：写完一段觉得"是不是还得加点 X"，先问 X 是不是当前用户能感知到的——不是就别加。整体写完一看 200 行其实 50 行能讲清楚 → 重写。多出来的代码不是中性的，是后人维护的负担。 + +### 2. 只动该动的，不顺手"改善"邻居 + +改某个函数时只改那个函数。同文件里别的函数风格丑、命名怪——除非和本次改动直接冲突，否则别碰。新代码风格匹配当前文件已有写法。混进的"顺手改"会把功能 PR 稀释成"一坨综合改动"，review 成本翻几倍。值得改的按下文"顺手发现"格式记成后续 issue。 + +孤儿处理：你这次改动让某个 import / 函数变成死代码 → 删掉。**不是**你改动造成的死代码 → 留着记成顺手发现。 + +### 3. design 没说的事别自己拍板 + +写到一半发现 design 没覆盖的角落（边界条件、错误路径、方案外文件）——默认停下来回 design 谈。下面"补丁分支"和"术语守护"是这条姿态的两个典型落点；**任何"design 没明说我替它选了一个"的瞬间都触发**。 + +--- + +## 启动检查 + +### 1. 方案文件够不够撑实现 + +frontmatter：`doc_type=feature-design` / `feature` 一致 / `status=approved` / `summary` 非空 / `tags` ≥ 2。 + +**标准 design**（节 0/1/2/3/4）： +- 第 0 节有内容；第 1 节含"明确不做"和复杂度档位 +- 第 2.1 名词层用"现状 → 变化"两段式，每个新增/变更接口至少一个示例 + 来源位置 +- 第 2.2 编排层开头有主流程图，"现状 → 变化"齐全，流程级约束已记 +- 第 2.3 挂载点按"删了它 feature 是否消失"判据，没把内部代码改动误列进来 +- 第 3 节有关键场景清单 + 反向核对项（不含测试代码 / framework 选型） + +**Fastforward design**（节 0/1/2/3）： +- 第 0 含"明确不做"；第 1 有改动点（文件 + 函数/类型名） +- 第 2 验收标准每条可验证；第 3 推进步骤有退出信号 + +任一项不达标 → 退回 `cs-feat` design 阶段 补齐。原因：方案漏的项实现时一定要现场补，等于绕过 checkpoint。 + +**注意**：标准 design 第 3 节"验收契约"只说"做完后什么应该成立"，不说"具体怎么做"。改动文件清单 / 函数级落点 / 测试代码归 implement 自决，不要因为 design 里没写就退回去要求补。 + +### 2. {slug}-checklist.yaml 在不在 + +- 文件存在，`feature` 字段一致 +- `steps` 非空（design 已产出，paradigm 维度切片，4-8 步）；`checks` 非空 +- 不存在 → 退回 `cs-feat` design 阶段 生成 + +### 3. 把上下文读全 + +- 方案 doc 全文（标准 design 重点：第 1 节、2.1/2.2/2.3/2.4、3） +- `{slug}-checklist.yaml`、需求来源（用户描述 + brainstorm note）、`.codestable/attention.md` +- 第 2.1 节接口示例的来源位置 / fastforward 第 1 节改动点提到的代码文件——读相关函数即可 +- 如果是 review-fix：读取 `{slug}-review.md`，只把 unresolved `blocking` findings 作为本轮目标 +- 如果是 qa-fix：读取 `{slug}-qa.md`，只把 failed / blocked QA items 作为本轮目标 + +### 4. 跟用户确认从哪一步开始 + +通常第 1 步；接续上次中断从已 `done` 的下一步继续。 + +design 给的 `steps` 是 paradigm 维度切片（编排骨架 → 计算节点 → 持久化 → 测试），**具体每步改哪个文件由你执行时决定**。如果某一步实际是 3 个独立子动作、或发现微重构是它的前置（参考反射检查），跟用户对齐后追加 / 拆分 steps，**不偷偷做**。 + +### 5. 基线预检 + +动第一行代码前，读取 design 里的"必跑验证命令 / 基线风险"。对本 feature 最相关、成本可接受的命令先跑一遍（至少 typecheck / targeted tests；前端可先确认 dev server / 页面入口可打开）。 + +- 全绿：在工作记录里记"基线预检通过：{命令列表}" +- 有红灯：先判断是既有问题还是本 feature 必须先修的前置 + - 既有红灯且不影响当前 feature：记录为基线风险，后续验证只要求"不新增失败 / targeted checks 通过"，最终汇报必须写清 + - 既有红灯但会影响当前 feature：停下来和用户确认，是先补 safety net / 修基线，还是调整 design + - 无法归因：不要继续大改，先缩小命令或读错误定位 + +这一步的目的不是把全仓库修绿，而是避免把"启动前已经坏"误判为本 step 失败，也避免在坏基线上继续堆代码。 + +**design 第 2.5 节微重构的衔接**： + +- 如果 2.5 结论是"做微重构（拆文件）"或"做微重构（重组目录）"，checklist 第 1 步就是它——**独立跑完**，按 2.5 节"行为不变怎么验证"那条核对： + - 拆文件：编译绿灯 + 现有测试通过 + 对外接口签名零 diff + - 重组目录：编译绿灯 + 现有测试通过 + diff 仅限文件移动 + import 路径更新（**没有任何函数体改动**） + + **不要合并到下一步**——一旦混在一起，行为变更和结构变更就分不开，出问题回滚不到干净中间态 +- 如果 2.5 结论是"不做"但写到中途反射检查触发了拆分信号 → 走下面"反射检查"那条路径（停下来 → 和用户对齐 → 能 provable 解决就追加独立 step），**不要绕过用户确认偷偷追加** +- 如果 2.5 末尾有"建议沉淀的 convention"段：implement 阶段**不主动归档**——只在重组目录跑通且行为零改动确认后，在汇报里带一句"design 2.5 建议沉淀的 convention 已就绪，等 acceptance 阶段确认是否走 cs-keep"，把决定权交给 acceptance / 用户 + +--- + +## 实现期间的几条核心约束 + +### 严格按 steps 顺序走 + +按 `steps` 列表顺序执行，不合并、不跳。每一步开始前先重读该 step 的 `action` / `exit_signal`，确认它是本轮唯一目标；每完成一步立即验证退出信号，并把 status `pending` → `done`。 + +最常见违规是"顺手把下一步也做了"——每步都对应独立可验证的退出信号，两步合做意味着出问题时不知道是哪一步引入的、回滚也回不到干净中间态。 + +每步完成后立刻把 `{slug}-checklist.yaml` 对应 step 状态落盘。不要等所有步骤完成再统一改；状态文件就是断点恢复锚点。中断恢复时先读它，而不是靠记忆。 + +### 每步都要有证据块 + +完成每个 step 后，在工作记录 / 汇报素材里留下最小证据： + +- 退出信号：原文摘出 +- 验证动作：跑了什么命令 / 看了什么页面 / 检查了什么 diff / 调了什么接口 +- 结果：通过 / 未通过；失败写真实错误摘要 +- 影响面：本步新增 / 修改的主要函数、类型、路由、配置或文档 +- 清洁度：本步新增代码里是否有调试输出、临时 TODO/FIXME、注释掉代码、无用 import、方案外文件 + +证据不要求每步都发给用户，但最终完成汇报必须能按 step 追溯。UI step 的证据不能只写 typecheck，必须有浏览器 / 截图 / 肉眼验证；后端接口 step 优先用测试或真实请求证明；纯类型约束可以用 typecheck 证明。 + +### Step 清洁度检查 + +每步验证时额外看本步 diff： + +- 新增调试输出：`console.log` / `console.error` / `print` / `fmt.Println` / 临时 logger +- 新增临时 TODO / FIXME / XXX +- 注释掉的旧代码或大段死代码 +- 新增 import 但未使用 +- 非本 step 需要的文件改动 + +命中就按失败处理：能当场删掉就删并重跑验证；确实是功能的一部分（例如新增日志能力）必须在 design / 汇报里说明原因和范围。清洁度不是审美问题，它是防止临时施工痕迹进入后续阶段。 + +### 不做方案外的改动 + +发现值得重构的点（参考 `.codestable/reference/shared-conventions.md` 第 7 节"写代码时的反射检查"），只要**不在本次功能影响面内**就记成后续 issue： + +```markdown +> 顺手发现：{文件:行号} {问题简述}。不在本次范围，记录待后续 issue。 +``` + +顺手改的代码不在方案里，验收对不上；后人 git blame 也分不清是为本次功能还是顺手。 + +### 术语守护 + +**标准 design**：新写的类型 / 函数 / 变量名都要去方案 doc 第 0 节对照，不允许出现 doc 里没有的新概念。要引入新概念 → 先停下来改第 0 节、grep 防冲突、用户确认。 + +**Fastforward design**：没有正式术语表，但要新起概念名时也要 grep 一下当前代码防冲突。 + +代价：术语冲突意味着同概念两个名字 / 同名字两个概念——后者会让搜索完全失效。 + +### 出现"补丁分支"的冲动时停下来 + +写代码时冒出 `if (特殊情况) { 特殊处理 }` 这种结构，**停**。这种分支基本只有一个原因：方案没覆盖到这种情况。继续写得到的是"为了让代码能跑而加的特殊逻辑"——下次别人改这块时不知道这个分支为什么存在。回方案谈：补进 design / 砍掉 / 明确为遗留问题。 + +### Step 失败恢复：诊断 → 窄修复 → 交还 + +某个 step 的退出信号或相关测试失败时，不直接推进下一步，也不把失败掩进最终汇报。按三段处理： + +1. **第一次失败：失败诊断** + 写清失败项、实际错误、刚改过的范围、根因假设；只围绕当前 step 做一次重试。重试前不要扩大 scope。 +2. **第二次失败：窄范围修复说明** + 如果重试仍失败，在 feature 目录写一份临时 `{slug}-step-N-fix.md`（或在完成汇报中等价记录）： + - 失败的 exit_signal / checks + - 根因判断 + - 只允许改哪些文件 / 行为 + - 修复后必须重跑哪些验证 + 执行这份窄修复，成功后回到原 step 的验证，不直接标 done。 +3. **第三次失败：交还用户** + 仍失败就停下来，报告三次尝试、证据、当前风险和建议下一步。不要为了"完成流程"继续改大范围代码。 + +这个机制只处理当前 step 的失败，不是绕过 design 的许可证。发现设计缺口仍然回 `cs-feat` design 阶段，不是用窄范围修复说明现场拍板。 + +### 用户中断与续跑 + +如果用户在实现中途发来新消息： + +- 当前 step 未到安全点：先把正在做的最小变更验证 / 回滚到可解释状态，再回应 +- 当前 step 已验证：更新 checklist 状态和证据后停在下一步开始前 +- 用户要求改方向：不要继续执行旧 checklist；先判断是改 design、拆 step、还是取消当前 feature + +恢复时固定顺序：读 design → 读 checklist 当前状态 → 读最近实现汇报 / 临时 step fix 文档 → 从第一条 `pending` step 继续。 + +### 代码质量反射检查 + +除上面流程约束外，还有一组针对代码质量的反射检查——看 `.codestable/reference/shared-conventions.md` 第 7 节。 + +核心：**不是"超过 N 行必须拆"，而是"遇到 X 情况就停下来问自己"**。每条对应 AI 默认会走进去的坑（往大文件继续追加、往大类加方法、补丁分支、复制粘贴、第 4+ 个参数、往万能 util 堆东西）。 + +反射检查结论是"要拆 / 新建文件 / 重命名 / 抽共用层"且超出现有 steps 范围 → 跟用户商量决定，不偷偷拆完继续写。判据按和 design 2.5 一致的边界分两路（避免 impl 自己造一套口径）： + +- **能用"只搬不改行为"解决**（拆函数 / 拆文件 / 移动定义，编译器全程绿灯，对外签名零 diff）→ 和用户对齐后**追加为独立 step**插在当前 step 之前，跑完独立验证退出再继续 +- **超出"只搬不改行为"边界**（要改函数签名 / 改返回值结构 / 改调用关系语义 / 模块拆合）→ **本 feature 不做**，记成"顺手发现"格式提示用户后续走 `cs-refactor`，当前 step 用最少的改动绕过去；不要因为"反正都看到了"就在 feature 里顺手做掉——这会把功能 PR 稀释成综合改动，也违反 design 2.5 早就划好的边界 + +### 最后一轮本地审计 + +所有 steps 标 `done` 后，完成汇报前做一轮小型 final audit： + +1. 重读 `{slug}-design.md` 第 1 / 2 / 3 节和 `{slug}-checklist.yaml` +2. 逐条确认 steps 全 done、checks 还未验收但已有实现证据 +3. 重新跑本 feature 所需的 build / typecheck / lint / test 或项目等价命令；有前端改动则跑浏览器验证 +4. 过一遍 `git diff`，检查本次新增的 debug 输出、临时 TODO/FIXME、注释掉的代码、无用 import、方案外文件 +5. 用第 3 节关键场景倒查：有没有某条没有证据；没有就补测或回实现 +6. 列出实际交付物：新增 / 修改 / 删除的代码入口、配置、schema、路由、文档、roadmap 状态，为 acceptance 的交付物复核做索引 +7. 列出知识候选：项目命令、环境坑、稳定 convention、库 API 坑、用户确认的偏好；不直接写入 knowledge，只交给 acceptance 第 8 节处理 + +audit 发现问题就回到对应 step 处理，不把问题留给 acceptance 首次发现。 + +### review-fix 模式 + +当 `cs-code-review` 产出 `status: changes-requested` 且有 unresolved `blocking` findings 时，进入 review-fix 模式： + +1. 只读取并修复 review 报告里的 blocking findings；不要借机实现新需求、重构邻居或处理非阻塞建议。 +2. 每个 REV 编号都要留下修复证据：改动文件、验证命令、为什么阻塞已解除。 +3. 如果修 blocking 需要改变 design 契约、扩大 feature 范围或触碰 roadmap item 边界，停下来回 `cs-feat` design 阶段 / 用户确认。 +4. 修完后跑相关验证和清洁度检查，输出 review-fix 汇报。 +5. 下一步必须重跑 `cs-code-review`；不能直接进入 `cs-feat` acceptance 阶段。 + +review-fix 不要求 checklist 新增普通 step，除非用户明确要求把修复动作纳入 checklist 追踪。默认把 REV 编号和证据写在汇报里，保留 review 报告作审查输入。 + +### qa-fix 模式 + +当 `cs-feat` QA 阶段 产出 `status: failed` 或 `status: blocked` 且失败项归因于本 feature 时，进入 qa-fix 模式： + +1. 只读取并修复 QA 报告里的 failed / blocked items；不要借机处理新需求、非阻塞建议或 review 已接受的 residual risk。 +2. 每个 QA 编号都要留下修复证据：改动文件、验证命令、为什么失败已解除。 +3. 如果修 QA 失败项需要改变 design 契约、扩大 feature 范围或触碰 roadmap item 边界，停下来回 `cs-feat` design 阶段 / 用户确认。 +4. 修完后跑相关验证和清洁度检查，输出 qa-fix 汇报。 +5. qa-fix 改变了代码 diff，下一步必须重跑 `cs-code-review`；review passed 后再重跑 `cs-feat` QA 阶段。不能直接进入 `cs-feat` acceptance 阶段。 + +qa-fix 不要求 checklist 新增普通 step，除非用户明确要求把修复动作纳入 checklist 追踪。默认把 QA 编号和证据写在汇报里，保留 QA 报告作复测输入。 + +--- + +## 写完后输出统一汇报 + +所有步骤完成后，按 `support/reference.md` 的"实现完成汇报"模板输出并停等用户 review。模板必须列出真实 `git status`、按步骤归类的改动、方案外触碰、新概念、step 证据、清洁度、交付物、知识候选、最后一轮本地审计和验收场景自检。 + +--- + +## 测试用例怎么落 + +标准 design 第 3 节"关键场景清单"每条 = 一个可验证行为约束。把每条变成可观察证据：单测 / 集成 / 手工操作 / 类型编译期保证。coding step 适合自动化测试时，可在 step 内采用 TDD vertical slice；这是 `cs-feat` implementation 阶段的内嵌实现策略，不是切换到独立 `tdd` skill。具体测试策略看 `support/reference.md` 和 `support/tdd.md`。 + +--- + +## 退出条件 + +完整 checklist 见 `support/reference.md`。主文件保留硬门摘要： + +- [ ] 所有 steps 的 status 都 `done`，且每步有退出信号证据。 +- [ ] 完成汇报已输出，用户 review 通过（或 review-fix / qa-fix 汇报已输出，等待重跑对应 gate）。 +- [ ] 没有未处理的"需要叫停"信号、方案外改动或清洁度缺口。 +- [ ] 开始前做过基线预检；完成前做过最后一轮本地审计。 +- [ ] 第 3 节关键场景每条都有证据 / 测试覆盖（fastforward 对照第 2 节）。 + +--- + +## 退出后 + +告诉用户下一步：普通实现完成后触发 `cs-code-review`；review-fix 后重跑 `cs-code-review`；qa-fix 后重跑 `cs-code-review` 和 `cs-feat` QA 阶段。不要顺手进入验收报告；完整话术见 `support/reference.md`。 + +--- + +## 容易踩的坑 + +完整列表见 `support/reference.md`。最常见红线：半成品汇报、方案外顺手改、新概念不回填、补丁分支硬冲、跳过 review/QA gate、关键场景没有证据。 diff --git a/plugins/codestable/skills/cs-feat-impl/references/reference.md b/plugins/codestable/skills/cs-feat/references/implementation/support/reference.md similarity index 92% rename from plugins/codestable/skills/cs-feat-impl/references/reference.md rename to plugins/codestable/skills/cs-feat/references/implementation/support/reference.md index 10d4137..ac1357c 100644 --- a/plugins/codestable/skills/cs-feat-impl/references/reference.md +++ b/plugins/codestable/skills/cs-feat/references/implementation/support/reference.md @@ -1,4 +1,4 @@ -# cs-feat-impl reference +# Feature Implementation Reference ## 写完后输出统一汇报 @@ -59,7 +59,7 @@ 具体怎么测、用什么 framework、mock 怎么搭——design 没规定，自决。但你得在 `steps` 里写清楚"哪一步落哪个测试"，汇报里逐项核对每条场景都有证据。 -coding feature / coding step 适合自动化测试时，按同目录 `tdd.md` 的 step 内 TDD 策略执行。它只约束当前 step 里的测试-实现微循环，不改变 `cs-feat-impl` 的 gate、checklist、证据、review / QA 流程。 +coding feature / coding step 适合自动化测试时，按同目录 `tdd.md` 的 step 内 TDD 策略执行。它只约束当前 step 里的测试-实现微循环，不改变 `cs-feat` implementation 阶段的 gate、checklist、证据、review / QA 流程。 **测试通过 ≠ 验收场景满足**——前者只说明你写的用例过了，不说明每条场景都有用例覆盖。 @@ -82,11 +82,11 @@ coding feature / coding step 适合自动化测试时，按同目录 `tdd.md` ## 退出后 -告诉用户："所有步骤完成，方案 doc 已同步。下一步阶段 2.5 代码审查，触发 cs-code-review。" +告诉用户："所有步骤完成，方案 doc 已同步。下一步阶段 2.5 代码审查，进入 cs-code-review。" -如果本轮是 review-fix，告诉用户："review blocking 已按范围修复。下一步重跑 cs-code-review；复审通过后再进入 cs-feat-qa。" +如果本轮是 review-fix，告诉用户："review blocking 已按范围修复。下一步重跑 cs-code-review；复审通过后再进入 `cs-feat` QA 阶段。" -如果本轮是 qa-fix，告诉用户："QA 失败项已按范围修复。下一步重跑 cs-code-review；review 通过后重跑 cs-feat-qa，再进入 cs-feat-accept。" +如果本轮是 qa-fix，告诉用户："QA 失败项已按范围修复。下一步重跑 cs-code-review；review 通过后重跑 `cs-feat` QA 阶段，再进入 `cs-feat` acceptance 阶段。" 别自己顺手开始写验收报告——验收需要独立的 checklist 节奏，提前进入会让把关失效。 @@ -100,7 +100,7 @@ coding feature / coding step 适合自动化测试时，按同目录 `tdd.md` - 引入新类型 / 概念但没回去更新方案 doc - 加 `if (用户是 X) { 特殊处理 }` 补丁分支而不停下来 - 用户 review 还没通过就自己进入代码审查或验收阶段 -- review-fix 修完后跳过 `cs-code-review` 直接进入 `cs-feat-accept` -- qa-fix 修完后跳过 `cs-code-review` 或 `cs-feat-qa` 直接进入 `cs-feat-accept` +- review-fix 修完后跳过 `cs-code-review` 直接进入 `cs-feat` acceptance 阶段 +- qa-fix 修完后跳过 `cs-code-review` 或 `cs-feat` QA 阶段直接进入 `cs-feat` acceptance 阶段 - 关键场景清单一条都没落证据 - 把 paradigm 维度 steps 当 file:line 读——steps 是切片策略不是改动清单；step 内部偷偷拆子步骤而不跟用户对齐 = 绕过 review diff --git a/plugins/codestable/skills/cs-feat-impl/references/tdd.md b/plugins/codestable/skills/cs-feat/references/implementation/support/tdd.md similarity index 89% rename from plugins/codestable/skills/cs-feat-impl/references/tdd.md rename to plugins/codestable/skills/cs-feat/references/implementation/support/tdd.md index 4fdca94..6102550 100644 --- a/plugins/codestable/skills/cs-feat-impl/references/tdd.md +++ b/plugins/codestable/skills/cs-feat/references/implementation/support/tdd.md @@ -1,12 +1,12 @@ # Step 内 TDD 策略 -这份 reference 是 `cs-feat-impl` 的内嵌实现策略，不是独立 skill 入口。不要切换到全局 `tdd` skill，也不要让 TDD 接管 CodeStable 的 gate、checklist、evidence、review / QA 流程。 +本文件是 `cs-feat` implementation 阶段的内嵌实现策略。只约束当前 step 的测试-实现微循环，不切换到全局 `tdd` skill，也不接管 CodeStable 的 gate、checklist、evidence、review / QA 流程。 ## 什么时候用 当前 feature / step 是代码实现任务，并且某个行为能用自动化测试可靠观察时，可以在该 step 内使用 TDD vertical slice。 -不要为了 TDD 改变已批准 design 的范围。要新增公共接口、行为语义或边界条件，先回到 `cs-feat-design` / 用户确认。 +不要为了 TDD 改变已批准 design 的范围。要新增公共接口、行为语义或边界条件，先回到 `cs-feat` design 阶段 / 用户确认。 ## 微循环 @@ -69,7 +69,7 @@ RED 时不重构。所有当前测试 GREEN 后，才检查这些候选： - shallow module：合并或深化模块，让接口小、实现深。 - feature envy：把逻辑移到数据或领域对象所在处。 - primitive obsession：在确有行为约束时引入 value object。 -- 新代码暴露的既有问题：若超出本 feature 范围，按 `cs-feat-impl` 的"顺手发现"记录，不顺手修。 +- 新代码暴露的既有问题：若超出本 feature 范围，按 `cs-feat` implementation 阶段的"顺手发现"记录，不顺手修。 ## 证据格式 diff --git a/plugins/codestable/skills/cs-feat/references/qa/protocol.md b/plugins/codestable/skills/cs-feat/references/qa/protocol.md new file mode 100644 index 0000000..a7e28df --- /dev/null +++ b/plugins/codestable/skills/cs-feat/references/qa/protocol.md @@ -0,0 +1,258 @@ +# Feature QA Protocol + +本阶段是 review 通过后、acceptance 前的 QA gate。它只读代码和产物、运行验证命令 / 浏览器 / API / 手工检查，并写 `{slug}-qa.md`。默认不改代码、不改 checklist、不改 design；发现失败后回到 `cs-feat` implementation 阶段的 qa-fix。 + +QA 的目标不是再做一遍 code review，也不是最终归档验收报告。它回答一个问题：在当前工作区里，design 承诺的关键行为是否有足够的运行证据，review 指出的测试焦点和 residual risk 是否被实际覆盖。 + +> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md` 第 0 节。 + +--- + +## 独立 QA Task agent（可选） + +QA 可以按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则，启用独立 runner 来执行浏览器、API、CLI、集成测试或环境复核，尤其是高风险功能、外部集成、真实浏览器路径和 goal 模式中的核心验收路径。但它是辅助执行者，不是 QA owner： + +- 主 agent 负责建立 Verification Matrix、决定哪些证据阻塞、核验 runner 输出，并写 `{slug}-qa.md` 的最终 verdict。 +- runner 默认只读代码和产物，只运行验证；如需改测试或配置，必须退回 `cs-feat` implementation 阶段 qa-fix。 +- runner 输出必须被写入 QA 报告的证据来源；未经主 agent 本地核验的结论只能作为 `residual-risk` 或待复核项。 +- 普通低风险非功能性 feature 不强制独立 runner，避免把 QA 成本固定放大。 + +--- + +## 输入 + +进入 QA 前必须读取： + +- `.codestable/attention.md` +- `{slug}-design.md` +- `{slug}-checklist.yaml` +- `{slug}-review.md` +- goal / gate 模式下的 `{slug}-evidence-pack.md`、`{slug}-gate-results.json`、`{slug}-dod-results.json` +- 实现完成汇报 / review-fix 汇报（如有） +- `git status --short` +- `git diff`（有 staged diff 时也读 `git diff --cached`） +- design 里的必跑验证命令 / 基线风险 / 验收场景 / 证据类型 / 清洁度规则 +- review 报告第 4 节 Test And QA Focus 和第 5 节 Residual Risk +- 项目测试入口：README、package scripts、Makefile、CI 配置、历史 acceptance / qa 报告里与本 feature 相关的命令 +- feature 性质判断：功能性 / 非功能性，以及哪些场景是核心验收路径 + +如果工作区有 feature 外的既有 dirty 文件，记录 baseline/无关变更；QA 结论只覆盖本 feature 可归因的改动。无法区分归因时写 `blocked` 或 `residual-risk`，不要假装通过。 + +--- + +## Feature 性质与证据硬门 + +QA 先判定 feature 性质，再决定必须拿到什么证据。这个判定写进 QA 报告，acceptance 会复核。 + +### 功能性 feature + +满足任一条件就按功能性处理： + +- 改变用户可见行为、UI、API、CLI、后台任务、权限、持久化、集成、运行时路由或错误语义。 +- roadmap / design 的成功标准里出现“用户能...”“系统会...”“真实请求 / turn / smoke / e2e / browser / API”等运行行为。 +- review 把某条验证标成必须覆盖，且它对应实际运行路径。 + +功能性 feature 的核心路径不能降级成 residual-risk： + +- design 第 3 节关键场景、checklist `checks`、roadmap success criterion、review Test And QA Focus 中属于核心功能路径的项，必须有实际运行证据：unit / integration / e2e / browser / API / CLI / manual smoke 任选合适组合，但证据必须能观察到行为。 +- 只跑 typecheck / lint / diff review，不能证明核心功能路径通过。 +- 外部凭证、服务、设备、网络或成本导致核心路径无法运行时，结论是 `blocked`；如果实现明显缺测试或行为失败，结论是 `failed`。 +- 只有 design 在实现前已明确把某条路径定义为“条件性非阻塞”（例如 CI 无 auth 时只验证 unavailable path），且 QA 已验证替代路径和 skip reason，才允许把这条写成 residual-risk。QA 现场不能临时把原本的核心验收路径改成非阻塞。 + +### 非功能性 feature + +以下类型默认按非功能性处理，除非它同时改变运行行为： + +- 文档、architecture / roadmap / requirement / learning 回写。 +- 纯重构、命名整理、目录迁移、死代码清理，且声明行为不变。 +- 测试补强、类型补强、lint/build 配置、脚本整理、生成物同步。 +- 内部设计文档、协议说明、agent skill 文案更新。 + +非功能性 feature 不强制 e2e / browser / API / 手工真实链路；它可以用静态检查、diff 复核、文档一致性、类型检查、构建、目标测试、快照或 schema 校验通过。QA 报告必须写明“不需要端到端运行验证”的理由，以及本 feature 实际采用的替代证据。 + +如果非功能性 feature 触碰了生产路由、用户可见文案、权限、安全边界、数据迁移或外部集成，即使目标是“重构/整理”，相关触碰点仍按功能性核心路径验证。 + +## 启动检查 + +1. `{slug}-design.md` 存在且 `status=approved`。 +2. `{slug}-checklist.yaml` 存在，`steps` 全 `done`，`checks` 仍未由 acceptance 全部通过。 +3. `{slug}-review.md` 存在，frontmatter `doc_type=feature-review`、`status=passed`，无 unresolved `blocking` findings。 +4. goal / gate 模式下，evidence pack、gate results、DoD results 必须存在；gate warnings 和 Residual Risks 纳入 QA matrix。 +5. 如果 review 报告不是基于当前 diff：先回 `cs-code-review` 复审。qa-fix 或其他代码改动会让旧 review 过期。 +6. 如果已有 `{slug}-qa.md`： + - `status=passed` 且 diff 未变化：提示可进入 `cs-feat` acceptance 阶段。 + - `status=failed` / `blocked`：读取旧失败项，确认是否处于 qa-fix 后的复测。 + - diff 已变化：重新 QA，并在报告里记录轮次。 + +--- + +## QA 流程 + +### 1. 建验证矩阵 + +从 design 第 3 节关键场景、design 必跑命令、review Test And QA Focus、review residual risk、evidence pack 的 Validation Commands / DoD Results / Residual Risks 汇总 QA 矩阵： + +- Feature type：functional / non-functional / mixed。 +- 核心性：core-functional / supporting / non-functional。 +- 场景：输入 / 触发 → 期望可观察结果。 +- 证据类型：unit / function / integration / e2e / browser / API / manual / typecheck / diff。 +- 命令或动作：具体命令、页面路径、API 请求、手工步骤。 +- 失败判据：什么结果算 fail，不写"看起来正常"。 +- 归因：本 feature / 既有基线 / 环境不可用 / 无法判断。 + +优先使用项目已有测试入口和既有工具，不为了 QA 临时引入新测试框架。需要新增测试代码时，QA 不直接写；把它记为 failed item，回 `cs-feat` implementation 阶段 qa-fix。 + +### 2. 运行验证 + +按从便宜到昂贵、从自动到手工的顺序运行： + +1. 基线相关命令：typecheck / lint / build / targeted unit 或项目等价命令。 +2. 与 feature 直接相关的 unit / function / integration / e2e 测试。 +3. review 与 evidence pack 指出的重点验证、gate warnings 和 residual risk。 +4. 功能性前端 / 用户可见改动：浏览器验证、截图或明确手工路径；只跑 typecheck 不算 QA 通过。 +5. 功能性 API / 后端 / 运行时能力：真实请求、集成测试或可复现的命令行调用。 +6. 非功能性改动：静态检查、diff 复核、文档一致性、schema/快照/类型/构建/目标测试，并记录为什么无需端到端运行。 +7. 清洁度复核：debug 输出、临时 TODO/FIXME、注释掉代码、无用 import、方案外文件。 + +每条证据必须记录命令、退出码或观察结果。命令不可运行时写具体原因：缺依赖、服务不可启动、外部凭证缺失、环境限制、成本过高。不可运行不是自动通过。 + +### 3. 判定 + +- `passed`：所有 blocking QA items 通过；功能性核心路径都有运行证据；非功能性 feature 有充分替代证据和“不需要端到端运行”的理由；不可运行项只剩非核心 residual risk。 +- `failed`：关键场景失败、必跑命令失败且归因本 feature、review 重点未覆盖、测试缺口会影响验收可信度、功能性前端未做浏览器验证、功能性 API / 运行时路径没有实际调用证据。 +- `blocked`：输入缺失、review 未通过、环境不可用到无法判断核心行为、dirty diff 归因不清。 + +QA failed 时不要直接修代码。输出报告后进入 `cs-feat` implementation 阶段 qa-fix；qa-fix 修完必须先重跑 `cs-code-review`，再重跑 `cs-feat` QA 阶段。 + +`residual-risk` 只能承载非核心风险、明确延期项或非功能性无法完全复核的边界。它不能承载“核心功能路径没跑过”“真实用户路径没验证”“必跑命令没执行”这类验收缺口。 + +--- + +## 报告模板 + +报告路径：`.codestable/features/{feature}/{slug}-qa.md`。 + +```markdown +--- +doc_type: feature-qa +feature: YYYY-MM-DD-slug +status: passed|failed|blocked +tested: YYYY-MM-DD +round: 1 +--- + +# {slug} QA 报告 + +## 1. Scope And Inputs + +- Design: {path} +- Checklist: {path} +- Review: {path} +- Evidence pack: {path / none} +- Gate results: {path / none} +- DoD results: {path / none} +- Diff basis: {git status / git diff 摘要} +- Baseline dirty files: {none / 列表 + 归因} +- Feature type: functional|non-functional|mixed +- Core evidence gate: {功能性核心路径列表；非功能性写不需要端到端运行的理由} + +## 2. Verification Matrix + +| ID | 来源 | 核心性 | 场景 / 风险 | 证据类型 | 命令或动作 | 期望 | 结果 | +|---|---|---|---|---|---|---|---| +| QA-001 | design S1 | core-functional/supporting/non-functional | {描述} | unit/integration/e2e/browser/API/manual/typecheck/diff | `{命令}` | {期望} | pass/fail/blocked | + +## 3. Command Results + +- `{命令}` → exit {code}：{摘要} +- 未运行：{命令} → {具体原因 + 是否阻塞} + +## 4. Scenario Results + +- [ ] QA-001 {场景}：pass/fail/blocked + - Evidence: {输出 / 截图 / 请求响应 / 手工路径} + - Notes: {归因 / 风险} + +## 5. Findings + +### failed + +- [ ] QA-001 {失败项} + - Evidence: {证据} + - Impact: {为什么影响验收} + - Expected fix scope: {只描述失败边界，不替实现写方案} + +### blocked + +- [ ] QA-00N {阻塞项} + +### residual-risk + +- {无法完全验证但不阻塞的风险；没有写 none} +- 不允许出现：功能性核心路径未运行、真实用户/API/运行时路径未验证、必跑命令未执行。 + +## 6. Cleanliness + +- Debug output: pass/fail +- Temporary TODO/FIXME/XXX: pass/fail +- Commented-out code: pass/fail +- Unused imports / dead code from this feature: pass/fail +- Out-of-scope files: pass/fail + +## 7. Verdict + +- Status: passed|failed|blocked +- Next: `cs-feat` acceptance 阶段 | `cs-feat` implementation 阶段 qa-fix -> `cs-code-review` -> `cs-feat` QA 阶段 | 补齐环境后重跑 `cs-feat` QA 阶段 +``` + +没有某类 finding 时写 `none`，不要删除章节；复测要能对比。 + +--- + +## qa-fix 衔接 + +如果 QA `failed`： + +1. 报告 `status: failed`。 +2. 告诉用户下一步进入 `cs-feat` implementation 阶段的 qa-fix 模式。 +3. qa-fix 只修 QA failed / blocked items，不处理顺手发现，不扩大 feature 范围。 +4. qa-fix 修完会改变 diff，必须重跑 `cs-code-review`；review passed 后再重跑 `cs-feat` QA 阶段。 +5. QA passed 后才能进入 `cs-feat` acceptance 阶段。 + +如果 QA `blocked`： + +- 先补环境 / 输入 / review 状态；不把 blocked 写成通过。 + +如果 QA `passed`： + +- 告诉用户下一步是 `cs-feat` acceptance 阶段。 + +--- + +## 退出条件 + +- [ ] 已读取 attention、design、checklist、review、实现证据、git status、git diff。 +- [ ] 已确认 review passed 且基于当前 diff。 +- [ ] 已判定 feature type，并写明功能性核心路径或非功能性替代证据理由。 +- [ ] 已建立 verification matrix，覆盖 design 关键场景、必跑命令、review Test And QA Focus、review residual risk、evidence pack commands / residual risks，并标出每项核心性。 +- [ ] 已运行可运行的验证命令 / 浏览器 / API / 手工检查，并记录结果。 +- [ ] 功能性核心路径都有实际运行证据；缺失则 QA 为 failed / blocked，不能写 passed。 +- [ ] 非功能性 feature 如未做 e2e / browser / API，已写明为什么不需要，以及采用了哪些替代证据。 +- [ ] 未运行项都有具体原因和阻塞判断。 +- [ ] 已完成清洁度复核。 +- [ ] 已写 `.codestable/features/{feature}/{slug}-qa.md`。 +- [ ] failed / blocked 时没有进入 acceptance，而是指向 qa-fix 或补环境。 +- [ ] passed 时明确告诉用户下一步 `cs-feat` acceptance 阶段。 + +--- + +## 容易踩的坑 + +- 把 QA 写成第二次 code review，不运行任何证据。 +- 只跑 typecheck 就宣称前端用户路径通过。 +- 把功能性核心路径没跑过写成 residual-risk，然后仍然 passed。 +- 对文档 / 架构 / 测试补强类非功能性 feature 机械要求 e2e，而不是用更合适的静态 / 一致性 / 目标测试证据。 +- 命令失败但归因不清就写 passed。 +- QA 阶段直接修代码，绕过 qa-fix / review 复审。 +- qa-fix 后跳过 review，直接重跑 QA 或进入 acceptance。 +- 不记录未运行原因，导致 acceptance 无法判断剩余风险。 diff --git a/plugins/codestable/skills/cs-issue-analyze/SKILL.md b/plugins/codestable/skills/cs-issue-analyze/SKILL.md index 97656a0..2390c11 100644 --- a/plugins/codestable/skills/cs-issue-analyze/SKILL.md +++ b/plugins/codestable/skills/cs-issue-analyze/SKILL.md @@ -1,175 +1,23 @@ --- name: cs-issue-analyze -description: Issue 根因分析。触发：已有 report 后找根因、评估风险、给修复方案；不改代码。 +description: Issue analyze 兼容入口。旧调用保留；执行时转入 cs-issue 主流程的 analyze 阶段。 --- # cs-issue-analyze -## 启动必读 +本技能是 `cs-issue` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_stage: analyze` -用户已把问题描述清楚，你的活是**通过实际读代码找根因**——不是脑子里推断、不是在报告基础上猜。读代码是核心动作，跳过它写出来的分析没价值。 +## 执行规则 -分析完不直接动手——给用户看 2-3 种修复方案让 TA 选。原因：根因往往有多种修法，影响面 / 副作用 / 改动范围各不相同，这是用户该拍板的事。 +1. 按已安装 skill 名称加载 `cs-issue` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-issue` 主协议继续执行，并带上入口意图 `requested_stage: analyze`。 +3. 不要要求用户重新调用 `cs-issue`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md` 第 0 节和 `cs-issue` 的"文件放哪儿"。 +## 维护规则 ---- - -## 启动检查 - -1. **问题报告存在且已确认**——读 `{slug}-report.md`，确认 `doc_type=issue-report` 且 `status=confirmed`，5 节都有内容。不完整 / 状态不对 → 回 `cs-issue-report`。`cs-issue-report` 已判走标准路径就按标准路径走，不二次改判 -2. **断点恢复**——`{slug}-analysis.md` 已存在则检查 5 节哪些已填： - - 全部填满但 `status=draft` → 跳到 checkpoint - - 部分填写 → 汇报"上次做到第 X 步，从第 Y 步继续" -3. **把上下文读全**： - - 问题报告全文 + `.codestable/attention.md` - - 报告里提到的相关文件（用 Glob / Grep 找别只凭描述） - - **扫 .codestable/ 全局**——Glob `.codestable/` 发现可用输入，按需取用：`requirements/CONTEXT.md` + `requirements/adrs/`（涉及领域术语 / 拍板决策时读）、`compound/`（`grep -r` 关键词搜历史沉淀，命中在分析开头标注引用）、`requirements/{slug}.md`（涉及能力边界时读） - ---- - -## 分析的五步 - -每步都要**真正读代码**不要靠推测。 - -### 步骤 1：定位问题代码 - -按报告"涉及模块 / 复现步骤"用 Grep / Glob 找：搜函数名 / 类名 / 文件名；沿调用链追溯（用户入口往下找）；重点看条件分支 / 边界值 / 状态更新 / 异步 / 数据流转。 - -记关键位置：`{文件}:{行号} — {这里干什么}`。 - -### 步骤 2：还原失败路径 - -对照复现步骤把代码执行路径走一遍：用户触发什么 → 调哪个函数 → 数据怎么流 → 哪里分叉走错。描述"正常路径"和"失败路径"的分叉点。**分叉点 = 根因候选**。 - -### 步骤 3：确认根因 - -单一 vs 多个根因；多个根因列出主次。 - -**根因分类**： -- 逻辑错误（条件判断 / 边界值缺失） -- 状态污染（副作用影响后续流程） -- 数据格式（输入 / 输出格式假设不符实际） -- 并发 / 竞态（异步顺序 / 共享状态） -- 配置 / 环境（依赖未稳定的配置） -- 缺少防御（没处理 null / undefined / 空列表等边界） - -### 步骤 4：影响面评估 - -- **影响范围**：只影响报告场景，还是更多场景？ -- **潜在受害者**：哪些其他功能 / 模块可能被同一根因波及？ -- **数据完整性**：会不会导致数据损坏或状态不一致？ -- **严重程度复核**：和报告 P0/P1/P2/P3 对比是否需要调整？ - -为什么复核：report 阶段给的是基于现象的判断，分析后看到了影响面——往往发现问题比看上去严重或没那么严重。 - -### 步骤 5：修复方案选项 - -列 2-3 种方向，每种说明：做什么（改哪里、怎么改）/ 优点 / 缺点和风险 / 影响面（会动哪些文件、影响其他功能吗）。 - -**推荐方案**：在 2-3 种里挑一种说明理由（通常：改动范围最小 + 根因最直接 + 副作用最少）。 - ---- - -## 根因分析模板 - -```markdown ---- -doc_type: issue-analysis -issue: {issue 目录名} -status: draft -root_cause_type: logic | state-pollution | data-format | concurrency | config | missing-guard -related: [{slug-report.md 相对路径}] -tags: [] ---- - -# {问题简述} 根因分析 - -## 1. 问题定位 - -| 关键位置 | 说明 | -|---|---| -| `{文件}:{行号}` | {干什么，为什么有问题} | - -## 2. 失败路径还原 - -**正常路径**：{用户做 A → 调用 B → 数据经过 C → 结果 D（符合期望）} - -**失败路径**：{用户做 A → 调用 B → 在 C 处因为 E 走了错误分支 → 结果 F（不符合期望）} - -**分叉点**：`{文件}:{行号}` — {为什么这里走错} - -## 3. 根因 - -**根因类型**：{...} - -**根因描述**：{一段话说清为什么会发生，要能让没看过代码的人理解} - -**是否有多个根因**：{是 / 否。是的话列出主次} - -## 4. 影响面 - -- **影响范围**：{只影响报告场景 / 还会影响 X、Y、Z} -- **潜在受害模块**：{列出可能被波及的} -- **数据完整性风险**：{有 / 无。有的话说明} -- **严重程度复核**：{维持 P? / 调整为 P?，理由} - -## 5. 修复方案 - -### 方案 A：{方案名} -- **做什么**：{改哪里、怎么改} -- **优点**：{...} -- **缺点 / 风险**：{...} -- **影响面**：{会动哪些文件，会影响其他功能吗} - -### 方案 B：{方案名} -- ... - -### 推荐方案 - -**推荐方案 {A / B}**，理由：{改动范围最小 / 根因最直接 / 副作用最少 + 具体说明} -``` - ---- - -## checkpoint：和用户对齐 - -写完后**别直接开始修**： - -1. 把"根因"和"推荐方案"口头总结给用户（不让用户读整份文件——TA 在等结论） -2. 问"根因判断是否准确？推荐方案你认可，还是想选别的？" -3. 用户明确确认方案后才触发阶段 3 - ---- - -## 退出条件 - -- [ ] frontmatter 存在（`doc_type=issue-analysis` / `issue` 一致） -- [ ] 5 节都填完 -- [ ] 定位到具体代码位置（`{文件}:{行号}`） -- [ ] 失败路径还原清晰 -- [ ] 影响面评估完成 -- [ ] 至少 2 种修复方案 + 推荐 -- [ ] 用户明确确认"分析准确，用方案 X 修" -- [ ] frontmatter `status: confirmed` - ---- - -## 退出后 - -告诉用户："根因分析已就绪，方案已确认。下一步阶段 3 修复验证，触发 `cs-issue-fix`。" - -别自己顺手改代码——跨阶段无停顿往下跑会让用户来不及把关。 - ---- - -## 容易踩的坑 - -- 根因写"可能是某处的问题"——必须定位到 file:line -- 没读代码就靠问题描述推断——一定要实际 Grep / Read -- 只列一种修复方案——至少两种 -- 分析完直接开始改代码——必须等用户确认 -- 影响面写"可能影响其他功能"——要具体说哪些 -- 严重程度复核总是"维持"——认真看影响面，升级的要改 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-issue` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-issue-fix/SKILL.md b/plugins/codestable/skills/cs-issue-fix/SKILL.md index 8404f87..d3eed4e 100644 --- a/plugins/codestable/skills/cs-issue-fix/SKILL.md +++ b/plugins/codestable/skills/cs-issue-fix/SKILL.md @@ -1,170 +1,23 @@ --- name: cs-issue-fix -description: Issue 定点修复。触发：按根因方案修 bug、动手改代码；只动方案声明范围。 +description: Issue fix 兼容入口。旧调用保留；执行时转入 cs-issue 主流程的 fix 阶段。 --- # cs-issue-fix -## 启动必读 +本技能是 `cs-issue` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_stage: fix` -根因和方案已经确定（标准路径在 analysis、快速通道在 report 阶段口头确认过），你的活是按方案改代码、验证效果、写下修复记录。 +## 执行规则 -fix 阶段最容易出问题的不是改代码本身，而是**改的过程中冒出的"顺手"冲动**——顺手优化、顺手重构、顺手加抽象。每项单独看说得通，但合在一个 PR 里让别人分不清"这次到底为了修 bug 改了什么"。 +1. 按已安装 skill 名称加载 `cs-issue` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-issue` 主协议继续执行，并带上入口意图 `requested_stage: fix`。 +3. 不要要求用户重新调用 `cs-issue`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md` 第 0 节和 `cs-issue` 的"文件放哪儿"。 +## 维护规则 -## 执行 gate（worktree + commit） - -进入修复前运行 start gate，`{slug}` 为 issue 目录名： - -```bash -python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/issues/YYYY-MM-DD-{slug} -``` - -gate 不通过就不要开始改代码；用户批准 override 时先在 unit 目录写 `worktree-override.md`（reason / scope / approval）。 - -修复完成、输出汇报前运行 commit gate： - -```bash -python3 .codestable/tools/codestable-worktree-gate.py --root . --json commit --unit .codestable/issues/YYYY-MM-DD-{slug} -``` - -gate 不通过就先处理 findings，不把"测试已过"当成完成。gate 工具的安装与 branch-guard hook 说明见 `.codestable/reference/branch-guard-hooks.md`。 - ---- - -## 两种入口 - -### 标准路径（有 analysis） - -1. **方案已确认**——读 analysis，确认 `doc_type=issue-analysis` 且 `status=confirmed`，第 5 节用户选定了哪个方案 -2. **上下文读全**：analysis 全文 + report 全文 + analysis 第 1 节定位的所有代码 + `.codestable/attention.md` + 沉淀目录搜索： - - `grep -r "{关键词}" .codestable/compound/`——确认修复方式不违背已有库用法 / 模式 / 调研结论 -3. **确认起点**——告诉用户"我将按方案 X 修改 {文件列表}，开始修复"，等用户确认才动手 - -### 快速通道（无 analysis，从 report 直接触发） - -进入这个入口时 AI 在 report 阶段已读过代码并对根因有把握。 - -1. **明确陈述根因**："`{文件}:{行号}` 的 {具体代码} 存在 {问题描述}"，让用户确认根因判断准确 -2. **给修复方案**——改哪里、怎么改（一两句话，不写完整分析文档） -3. **等用户明确说"对，就这样改"才动手**——不允许"我觉得对，直接改了" -4. 读 `.codestable/attention.md` -5. **补搜沉淀目录**——快速通道也要查一遍 `compound/`（trick + explore），避免误把已知边界条件当新问题 - ---- - -## 实现期间的约束 - -先做 `shared-conventions.md` 第 7 节的**第一性原则 pre-pass**：外部行为就是"复现路径不再失败"，约束来自 report / analysis / fix 方案，最小充分改动只服务根因；从这三项推不出的抽象、兜底和顺手重构都不写。 - -### 只改 analysis 里声明的文件 - -修复范围来自 analysis 第 5 节"推荐方案"的"影响面"。超出范围的文件——哪怕顺眼——**不动**。 - -发现范围外值得改的记一条"顺手发现"不改代码： - -```markdown -> 顺手发现：{文件:行号} {问题简述}。不在本次修复范围，可后续另开 issue。 -``` - -为什么这么严：顺手改的代码不在分析里，验收对不上，git blame 分不清哪些改动是为这个 bug。 - -### 改动最小化 - -修复只针对根因，**不引入新抽象、新接口、新模式**。如果发现"要把这个改好得先重构 X"——停下来跟用户确认是否在这个 issue 里做重构，还是拆成独立工作。 - -为什么：bug 修复天然窄场景，引入新抽象意味着只有这一个使用点支撑——典型过早抽象。 - -### 代码质量反射检查 - -修 bug 看似动作小但 AI 写修复代码一样会漂——大文件再塞特殊处理、大类再加方法、为绕开边界加 `if` 分支。反射检查见 `shared-conventions.md` 第 7 节。 - -issue-fix 比 feature-implement 更谨慎：**触发反射信号但结论是"该拆"时默认不在本次 PR 做**——按"改动最小化"记成顺手发现。唯一例外是"不拆就没法干净修这个 bug"，那停下来跟用户确认"修这个 bug 的前置是 {重构动作}，合进来还是拆出去单独做"。 - -### 每完成一处改动必须汇报 - -修复汇报模板见同目录 `reference.md`，**不允许含糊汇报**。汇报后停下等用户回复。 - ---- - -## 验证清单 - -修复改完后逐项核对： - -- [ ] **复现步骤验证**——按 report 第 2 节走一遍，问题不再出现 -- [ ] **期望行为验证**——report 第 3 节"期望行为"现在确实发生 -- [ ] **影响面回归**——analysis 第 4 节"潜在受害模块"每个走一遍最基本的冒烟路径 -- [ ] **前端改动浏览器验证**（如涉及）——按 `.codestable/attention.md` 的硬要求执行，不能只 typecheck -- [ ] **相关测试通过**——有测试覆盖到修复区域就跑一遍 - ---- - -## 修复未生效时：日志调试升级 - -走完验证清单仍**问题复现**或行为与期望不符——**别在原有猜测上反复试错**，切换到日志调试模式重新收集运行时证据。 - -为什么切换：反复试错本质是猜测在原假设下还有什么可能性，但如果原假设就错了再猜也是绕圈。日志强制看实际运行时数据，往往一眼看出原假设哪里偏了。 - -日志调试步骤、用户取日志提示词、循环限制见同目录 `reference.md`。 - ---- - -## 写 {slug}-fix-note.md - -验证通过后在 issue 目录建 `{slug}-fix-note.md`（位置见 `cs-issue` 的"文件放哪儿"），记录完整闭环。标准路径模板和快速通道模板都在同目录 `reference.md`。 - ---- - -## 退出条件 - -- [ ] 所有改动文件已提交或列清单 -- [ ] 验证清单全部勾选 -- [ ] `{slug}-fix-note.md` 已建并填写完整 -- [ ] 没有未处理的"顺手发现"（都进后续 issue 列表） -- [ ] 没有范围外改动（或已和用户确认） -- [ ] 用户明确确认修复完成 - ---- - -## 收尾提交 - -按 `shared-conventions.md` 第 4 节"scoped-commit"规则执行。本阶段： - -- **提交范围**：修复代码 + `{slug}-fix-note.md` + 本次一并更新的 report / analysis -- 修复闭环后告诉用户"修复验证已完成，`{slug}-fix-note.md` 已落盘"，紧接着问是否需要 commit - ---- - -## 退出后 - -告诉用户："issue 修复完成，工作流闭环。report + analysis + fix-note 已存档。" - -按 `shared-conventions.md` 第 3 节"issue-fix"收尾推荐顺序各问一句（用户"不用"立即跳过）： - -0. 完成后先进入 `cs-code-review` 做独立 diff 评审；Critical/Important 未清零不进 commit，scoped-commit 发起权归 `cs-code-review`。 -1. 暴露的坑点 / 长期约束 / 规约 / 技术决定 → "沉淀到 compound？（`cs-keep`）" -2. 这个 bug 暴露了项目通用的硬约束 / 命令陷阱 / 环境设置（一两行能讲清、CodeStable 技能每次启动都该知道）→ "记到 attention.md？（`cs-note`）" -3. 最后问是否代为提交。同意时按收尾提交规则执行 - -建议：把 issue 目录文件和代码改动放同一次提交方便追溯；"顺手发现"另开 `cs-issue-report` 处理别塞这个 PR。 - -修复中发现问题实际是功能缺失（不是 bug）→ 建议另开 `cs-feat`，别在 issue 工作流里偷偷做新功能。 - ---- - -## 容易踩的坑 - -- 修完没走验证清单就宣告"修好了" -- 顺手改了 analysis 范围外的代码 -- 修复引入新抽象 / 接口但没停下来确认 -- `{slug}-fix-note.md` 没建就宣告完成 -- 发现影响面回归有问题但写"轻微影响可忽略"——要修到干净 -- 前端改动只 typecheck 就报通过 -- 用户没明确说"修复完成"就结束 -- 修复未生效继续原假设上反复猜测试错，不切换到日志调试 -- 日志调试结束后没清理临时 log 就提交 -- 收尾时没问用户是否代为 commit -- 用户没明确同意就 `git commit` +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-issue` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-issue-report/SKILL.md b/plugins/codestable/skills/cs-issue-report/SKILL.md index c42879c..41a6d27 100644 --- a/plugins/codestable/skills/cs-issue-report/SKILL.md +++ b/plugins/codestable/skills/cs-issue-report/SKILL.md @@ -1,154 +1,23 @@ --- name: cs-issue-report -description: Issue 报告起草。触发：提 issue/记录 bug/发现问题；只问现象，不猜根因。 +description: Issue report 兼容入口。旧调用保留；执行时转入 cs-issue 主流程的 report 阶段。 --- # cs-issue-report -## 启动必读 +本技能是 `cs-issue` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_stage: report` -这一阶段做两件事：把用户脑子里的问题落成结构化记录 + 判断走标准路径还是快速通道。 +## 执行规则 -**核心原则：只记现象不记根因**。用户说"我觉得是 XX 组件的问题"——记下"用户怀疑 XX 组件"作为线索，但不顺着聊根因。根因要在阶段 2 通过实际读代码确认，不靠脑子里猜。混进根因猜测的报告会带偏阶段 2，让分析人围着错误线索绕。 +1. 按已安装 skill 名称加载 `cs-issue` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-issue` 主协议继续执行，并带上入口意图 `requested_stage: report`。 +3. 不要要求用户重新调用 `cs-issue`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md` 第 0 节和 `cs-issue` 的"文件放哪儿"。 +## 维护规则 ---- - -## 启动检查 - -1. **确认是 bug 不是新功能需求**——描述"想加 X 功能"的告诉他走 `cs-feat` -2. **看有没有相关 issue 目录**——Glob `.codestable/issues/`，有同类问题先和用户确认是新建还是更新 -3. **快速通道判断（唯一正式判定点）**——按用户线索**读一下相关代码**（Grep / Read 定位）： - - **能一眼确定根因**（能给出 `{文件}:{行号}`、修复改动小 1-2 处、无跨模块影响风险）→ 告诉用户"我已看到问题所在，可以走快速通道：直接告知根因和修复方案，你确认后我立刻修，修完你验证，只写一份 `{slug}-fix-note.md`"。同意后触发 `cs-issue-fix`（快速通道模式） - - **不能**（根因有多个候选 / 不确定 / 需要更多复现信息）→ 走标准路径做完整问题报告。进入标准路径后默认不再二次改判 -4. **确定 issue 目录名**——跟用户商定 slug，日期前缀用今天（环境信息 `currentDate`）。目录不存在就创建。快速通道也要建 issue 目录，`{slug}-fix-note.md` 放那 - ---- - -## 必答 5 问 - -按顺序逐个问，**不一次抛 5 个**——一次抛多个用户只回最容易的，深的就漏了。每问做一次模糊度检查，不通过继续追问。 - -### 1. 问题是什么？看到的现象？ - -期待具体的异常表现："点击提交按钮后弹出了空白弹窗" 比 "提交功能有问题" 有用一百倍。 - -模糊信号："有时候会出错"、"感觉不对" → 追问"具体什么时候"、"具体什么不对"。 - -红线：**不要让用户描述根因**。出现"应该是因为 XXX"——记现象，根因留给阶段 2。 - -### 2. 怎么复现？ - -期待最小复现步骤：进入 XX 页面 → 输入 YY → 点击 ZZ → 看到问题现象。 - -模糊信号："不稳定复现"、"有时候能有时候不能" → 追问复现频率和条件差异。确实不稳定就写明已知触发条件和复现率。 - -"无法复现"也是有效回答——写"目前无法稳定复现，只在 X 情况下观察到一次"，别勉强凑步骤。 - -### 3. 期望行为 vs 实际行为 - -期待两句话： -- **期望**：我以为做了 A 之后应该发生 B -- **实际**：但实际发生了 C - -**不要合并成一句**。合在一句"按钮没正常工作"里分析的人不知道"正常"长什么样。 - -### 4. 环境信息 - -最低采集：**在哪个模块 / 功能区域发现的**、**相关文件或函数（用户知道的话）**。 - -可选：操作系统、浏览器版本、运行环境（dev / prod）、最近有没有改过相关代码。 - -用户说"不知道在哪个文件"——写"待定"，阶段 2 分析时查。 - -### 5. 严重程度与优先级 - -- **P0 阻塞**：核心功能完全失效，影响所有用户，必须立刻修 -- **P1 严重**：核心功能受损有绕过方法，尽快修 -- **P2 中等**：非核心功能或影响少数用户，计划内修 -- **P3 轻微**：UI 瑕疵 / 边界情况 / 有更好实现，按空闲修 - -用户不确定就帮他推荐一个但让用户拍板。 - ---- - -## 问题报告模板 - -```markdown ---- -doc_type: issue-report -issue: {issue 目录名} -status: draft -severity: P0 | P1 | P2 | P3 -summary: {问题现象一句话} -tags: [] ---- - -# {问题简述} Issue Report - -## 1. 问题现象 - -{用户描述的具体异常表现，纯现象描述，不含根因推测} - -## 2. 复现步骤 - -1. {步骤 1} -2. {步骤 2} -3. 观察到：{问题现象} - -复现频率：{稳定 / 概率（约 X%） / 暂无法稳定} - -## 3. 期望 vs 实际 - -**期望行为**：{做了 A 应该发生 B} - -**实际行为**：{但实际发生了 C} - -## 4. 环境信息 - -- 涉及模块 / 功能：{模块名或功能描述} -- 相关文件 / 函数：{已知 file:line 或"待定"} -- 运行环境：{dev / staging / prod / 不确定} -- 其他上下文：{OS、浏览器、最近改动等，没有写"无"} - -## 5. 严重程度 - -**{P0 / P1 / P2 / P3}** — {一句话理由} - -## 备注 - -{可选：截图描述、日志片段等} -``` - ---- - -## 退出条件 - -- [ ] frontmatter 完整（`doc_type=issue-report` / `issue` 一致 / `severity` 和 `summary` 非空 / `tags` ≥ 1） -- [ ] 5 问都有具体答案（环境中相关文件可"待定"） -- [ ] 问题现象是纯现象描述，没混入根因推测 -- [ ] 期望 vs 实际显式分开写 -- [ ] 复现步骤可执行（"无法稳定复现"也有说明） -- [ ] 用户明确说"report 可以了，进下一步" -- [ ] frontmatter `status: confirmed` - ---- - -## 退出后 - -告诉用户："问题报告已就绪。下一步阶段 2 根因分析，触发 `cs-issue-analyze`。" - -别自己顺手开始分析根因——阶段间的人工 checkpoint 是工作流硬约束。 - ---- - -## 容易踩的坑 - -- 用户说"可能是 XX 的问题"你顺着聊根因——错，那是阶段 2 -- 复现步骤太模糊（"在用户界面操作一下"）就放行——逼出可执行步骤 -- 期望和实际混在一段话里——必须显式分开 -- 严重程度留空——给默认值或写"无" -- 一口气把 5 问列成清单丢给用户填——逐题对话否则深的全漏 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-issue` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-issue/SKILL.md b/plugins/codestable/skills/cs-issue/SKILL.md index a8a2ec0..8662274 100644 --- a/plugins/codestable/skills/cs-issue/SKILL.md +++ b/plugins/codestable/skills/cs-issue/SKILL.md @@ -1,6 +1,7 @@ --- name: cs-issue -description: Issue 流程路由。触发：修 bug/有问题/修复 XX；按状态进入 report/analyze/fix。 +description: Issue 主入口。触发：修 bug/有问题/修复 XX；端到端推进 report、analyze、fix、review。 +argument-hint: "[report|analyze|fix] [问题描述]" --- # cs-issue @@ -9,96 +10,87 @@ description: Issue 流程路由。触发：修 bug/有问题/修复 XX；按状 开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 -修 bug 直觉是"找到错的地方改了完事"，但这个直觉路径反复制造同样的麻烦： +`cs-issue` 是问题修复的唯一推荐入口。它负责把问题从记录、根因分析、定点修复、验证、fix-note 和 code review 衔接到闭环。 -1. 问题描述只在脑子里改完就忘——三个月后 bug 再现没复现步骤留存 -2. 根因没分析就动手——改了表面现象深层问题等下次爆发 -3. 修复范围扩散——发现一个 bug 顺手改五处引入新问题，无法追溯 -4. 没验收闭环——怎么判断改好了？改好了什么？没记录 +旧阶段技能 `cs-issue-report`、`cs-issue-analyze`、`cs-issue-fix` 长期保留为兼容入口，只传入 `requested_stage`。 -issue 工作流在"看到问题"和"动手改代码"之间塞缓冲： +--- -``` -发现问题 → 清晰记录（report）→ 根因分析（analyze）→ 定点修复 + 验证（fix） -``` +## 入口意图 -本技能不写任何东西，只看当前 issue 走到哪步、决定触发哪个子技能。 +本次调用参数：$ARGUMENTS + +意图来源按优先级：调用参数 > 兼容入口预设 > 用户话术。参数为空或未被替换（仍是字面 `$ARGUMENTS`）时跳过该来源；首个 token 命中 `report` / `analyze` / `fix` 则设为对应 `requested_stage`，其余文本作为问题描述。 + +入口意图不覆盖仓库事实。若 report 已存在但用户从 report 兼容入口进来，继续 analyze；若代码已改但无 fix-note，进入 fix 验证/记录。 --- ## 文件放哪儿 -``` +```text .codestable/issues/{YYYY-MM-DD}-{slug}/ -├── {slug}-report.md ← 阶段 1 问题报告 -├── {slug}-analysis.md ← 阶段 2 根因分析 -└── {slug}-fix-note.md ← 阶段 3 修复记录（必出产物） +├── {slug}-report.md +├── {slug}-analysis.md +└── {slug}-fix-note.md ``` -日期取**发现 / 提报问题当天**定了不动。slug 能一眼看出是什么问题（`auth-token-leak`、`null-pointer-on-empty-list`）。 - -`{slug}-fix-note.md` 是阶段 3 **必出产物**——无论修复简单还是复杂都要写。它不是仪式，是回溯凭证：没有它下次类似问题来你只能从 git log 反推。 - -所有 issue 文档带 YAML frontmatter（`doc_type` 分别为 `issue-report` / `issue-analysis` / `issue-fix`）便于 `search-yaml.py` 按 severity / tags / status 检索。 +日期取发现/提报问题当天。`fix-note.md` 是必出产物，即使走快速通道也要写。 --- -## 两条路径 +## 状态机 -### 标准路径（问题复杂或根因不明） +启动后扫描 `.codestable/issues/`、读取目标 issue 产物、检查当前 git diff： -| 阶段 | 子技能 | 主导 | 产出 | -|---|---|---|---| -| 1 问题报告 | `cs-issue-report` | 用户描述，AI 引导 | `{slug}-report.md` | -| 2 根因分析 | `cs-issue-analyze` | AI 读代码分析，用户确认 | `{slug}-analysis.md` | -| 3 修复验证 | `cs-issue-fix` | AI 按分析定点修复，用户验证 | 代码 + `{slug}-fix-note.md` + scoped-commit | - -阶段间有人工 checkpoint——让用户在每阶段结束有一次明确把关，防止 AI 一口气从问题跑到代码跑出来才发现走偏。 - -### 快速通道（问题简单、根因一眼确定） - -下面**同时满足**才进： - -1. AI 读完代码后对根因高度有把握（能明确指出 file:line + 原因） -2. 修复改动很小（1-2 处） -3. 无跨模块影响风险 - -流程压缩成：AI 读代码 → 直接告知根因 + 修复方案 → 用户确认 → AI 修复 → 用户验证通过 → AI 写 `{slug}-fix-note.md`。只产出一份 `fix-note.md`，省掉 report 和 analysis。 - -**判定口径**：是否进快速通道由 `cs-issue-report` 的启动检查做唯一正式判定。一旦进标准路径默认不再二次改判——避免三个阶段对路径各说各话。 - -**不能**走快速通道：根因有多个候选 / 修复范围涉及多模块 / 需要先复现才能定位 / 用户希望留完整分析存档。 - ---- - -## 路由 - -进入本技能先 Glob `.codestable/issues/`，自己读已有文件才有数。 - -| 当前状态 | 触发哪个子技能 | +| 仓库事实 | 下一步 | |---|---| -| 刚发现问题，没有任何文件 | `cs-issue-report`（那里判断走标准还是快速） | -| `report.md` 已存在，没 `analysis.md` | `cs-issue-analyze` | -| `analysis.md` 已存在，代码还没改 | `cs-issue-fix` | -| 代码已改，还没修复验证记录 | `cs-issue-fix`（走验证） | -| 不确定 | 自己读已有文件按上表对号 | +| 没有 issue 文件 | 读取 `references/report/protocol.md` | +| report 存在，根因不明且无 analysis | 读取 `references/analyze/protocol.md` | +| report 存在，且读代码后确认根因明确、改动小、无跨模块影响 | 用户确认后直接进入 fix，仍写 fix-note | +| analysis 存在，代码未改 | 读取 `references/fix/protocol.md` | +| 代码已改但无 fix-note | 读取 `references/fix/protocol.md` 的验证/记录部分 | +| fix-note 已写但无 review | 进入公开横切 gate `cs-code-review` | +| review 有 blocking | 回 fix 窄修复，修完重跑 review | +| review passed | 汇报完成，并提示 docs/neat 候选 | -用户描述的是**新功能需求而不是 bug** → 告诉用户走 `cs-feat`。 +用户描述的是新增能力而不是坏掉的既有行为时，路由到 `cs-feat`。 --- -## 与 feature 工作流的边界 +## Reference 加载 -- issue：本来应该好的东西坏了——已有代码里的 bug / 异常行为 / 文档错误 / 性能问题 -- feature：从来没有的东西要加进来——新功能 / 新能力 +- report：`references/report/protocol.md` +- analyze：`references/analyze/protocol.md` +- fix：`references/fix/protocol.md`，必要时 `references/fix/reference.md` +- code review：公开横切技能 `cs-code-review` -灰色地带：修 issue 过程中发现需要新增能力才能真正解决——**先用 issue 工作流把记录和分析做完，再视情况开 feature**。不在 issue 里偷偷做新功能，理由跟 feature 不在 PR 里偷偷修 bug 一样：混着改分不清这次到底改了什么范围。 +按阶段加载，不一次性读完。 --- -## 相关文档 +## 快速通道 -- `.codestable/reference/system-overview.md` — CodeStable 体系总览 -- `.codestable/reference/shared-conventions.md` — 跨阶段共享口径 -- `.codestable/attention.md` — CodeStable 启动注意事项和项目硬约束 -- `.codestable/requirements/CONTEXT.md` + `requirements/adrs/` — 根因分析时可能要查的领域术语与拍板决策 +快速通道是 `cs-issue` 内部模式，不是单独技能。必须同时满足： + +1. 读代码后能指出明确根因。 +2. 修复很小，通常 1-2 处。 +3. 无跨模块影响风险。 + +不满足就走标准 report → analyze → fix。进入标准路径后默认不再二次改判，避免阶段之间口径漂移。 + +--- + +## 人工 checkpoint + +- report 阶段确认问题描述、复现、期望/实际、环境、严重度。 +- analyze 阶段确认推荐修复方案和风险。 +- fix 阶段验证结果和 review blocking 处理。 + +--- + +## 退出条件 + +- `{slug}-fix-note.md` 已写明根因、改动、验证和遗留风险。 +- 必要 code review 已通过或阻塞项已清楚交回。 +- 修复暴露新 feature 需求时，不在 issue 内偷做，另开 `cs-feat`。 diff --git a/plugins/codestable/skills/cs-issue/references/analyze/protocol.md b/plugins/codestable/skills/cs-issue/references/analyze/protocol.md new file mode 100644 index 0000000..24a1b7e --- /dev/null +++ b/plugins/codestable/skills/cs-issue/references/analyze/protocol.md @@ -0,0 +1,166 @@ +# Issue Analysis Protocol + +用户已把问题描述清楚，你的活是**通过实际读代码找根因**——不是脑子里推断、不是在报告基础上猜。读代码是核心动作，跳过它写出来的分析没价值。 + +分析完不直接动手——给用户看 2-3 种修复方案让 TA 选。原因：根因往往有多种修法，影响面 / 副作用 / 改动范围各不相同，这是用户该拍板的事。 + +> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md` 第 0 节和 `cs-issue` 的"文件放哪儿"。 + +--- + +## 启动检查 + +1. **问题报告存在且已确认**——读 `{slug}-report.md`，确认 `doc_type=issue-report` 且 `status=confirmed`，5 节都有内容。不完整 / 状态不对 → 回 `cs-issue` report 阶段。`cs-issue` report 阶段 已判走标准路径就按标准路径走，不二次改判 +2. **断点恢复**——`{slug}-analysis.md` 已存在则检查 5 节哪些已填： + - 全部填满但 `status=draft` → 跳到 checkpoint + - 部分填写 → 汇报"上次做到第 X 步，从第 Y 步继续" +3. **把上下文读全**： + - 问题报告全文 + `.codestable/attention.md` + - 报告里提到的相关文件（用 Glob / Grep 找别只凭描述） + - **扫 .codestable/ 全局**——Glob `.codestable/` 发现可用输入，按需取用：`requirements/CONTEXT.md` + `requirements/adrs/`（涉及领域术语 / 拍板决策时读）、`compound/`（`grep -r` 关键词搜历史沉淀，命中在分析开头标注引用）、`requirements/{slug}.md`（涉及能力边界时读） + +--- + +## 分析的五步 + +每步都要**真正读代码**不要靠推测。 + +### 步骤 1：定位问题代码 + +按报告"涉及模块 / 复现步骤"用 Grep / Glob 找：搜函数名 / 类名 / 文件名；沿调用链追溯（用户入口往下找）；重点看条件分支 / 边界值 / 状态更新 / 异步 / 数据流转。 + +记关键位置：`{文件}:{行号} — {这里干什么}`。 + +### 步骤 2：还原失败路径 + +对照复现步骤把代码执行路径走一遍：用户触发什么 → 调哪个函数 → 数据怎么流 → 哪里分叉走错。描述"正常路径"和"失败路径"的分叉点。**分叉点 = 根因候选**。 + +### 步骤 3：确认根因 + +单一 vs 多个根因；多个根因列出主次。 + +**根因分类**： +- 逻辑错误（条件判断 / 边界值缺失） +- 状态污染（副作用影响后续流程） +- 数据格式（输入 / 输出格式假设不符实际） +- 并发 / 竞态（异步顺序 / 共享状态） +- 配置 / 环境（依赖未稳定的配置） +- 缺少防御（没处理 null / undefined / 空列表等边界） + +### 步骤 4：影响面评估 + +- **影响范围**：只影响报告场景，还是更多场景？ +- **潜在受害者**：哪些其他功能 / 模块可能被同一根因波及？ +- **数据完整性**：会不会导致数据损坏或状态不一致？ +- **严重程度复核**：和报告 P0/P1/P2/P3 对比是否需要调整？ + +为什么复核：report 阶段给的是基于现象的判断，分析后看到了影响面——往往发现问题比看上去严重或没那么严重。 + +### 步骤 5：修复方案选项 + +列 2-3 种方向，每种说明：做什么（改哪里、怎么改）/ 优点 / 缺点和风险 / 影响面（会动哪些文件、影响其他功能吗）。 + +**推荐方案**：在 2-3 种里挑一种说明理由（通常：改动范围最小 + 根因最直接 + 副作用最少）。 + +--- + +## 根因分析模板 + +```markdown +--- +doc_type: issue-analysis +issue: {issue 目录名} +status: draft +root_cause_type: logic | state-pollution | data-format | concurrency | config | missing-guard +related: [{slug-report.md 相对路径}] +tags: [] +--- + +# {问题简述} 根因分析 + +## 1. 问题定位 + +| 关键位置 | 说明 | +|---|---| +| `{文件}:{行号}` | {干什么，为什么有问题} | + +## 2. 失败路径还原 + +**正常路径**：{用户做 A → 调用 B → 数据经过 C → 结果 D（符合期望）} + +**失败路径**：{用户做 A → 调用 B → 在 C 处因为 E 走了错误分支 → 结果 F（不符合期望）} + +**分叉点**：`{文件}:{行号}` — {为什么这里走错} + +## 3. 根因 + +**根因类型**：{...} + +**根因描述**：{一段话说清为什么会发生，要能让没看过代码的人理解} + +**是否有多个根因**：{是 / 否。是的话列出主次} + +## 4. 影响面 + +- **影响范围**：{只影响报告场景 / 还会影响 X、Y、Z} +- **潜在受害模块**：{列出可能被波及的} +- **数据完整性风险**：{有 / 无。有的话说明} +- **严重程度复核**：{维持 P? / 调整为 P?，理由} + +## 5. 修复方案 + +### 方案 A：{方案名} +- **做什么**：{改哪里、怎么改} +- **优点**：{...} +- **缺点 / 风险**：{...} +- **影响面**：{会动哪些文件，会影响其他功能吗} + +### 方案 B：{方案名} +- ... + +### 推荐方案 + +**推荐方案 {A / B}**，理由：{改动范围最小 / 根因最直接 / 副作用最少 + 具体说明} +``` + +--- + +## checkpoint：和用户对齐 + +写完后**别直接开始修**： + +1. 把"根因"和"推荐方案"口头总结给用户（不让用户读整份文件——TA 在等结论） +2. 问"根因判断是否准确？推荐方案你认可，还是想选别的？" +3. 用户明确确认方案后才触发阶段 3 + +--- + +## 退出条件 + +- [ ] frontmatter 存在（`doc_type=issue-analysis` / `issue` 一致） +- [ ] 5 节都填完 +- [ ] 定位到具体代码位置（`{文件}:{行号}`） +- [ ] 失败路径还原清晰 +- [ ] 影响面评估完成 +- [ ] 至少 2 种修复方案 + 推荐 +- [ ] 用户明确确认"分析准确，用方案 X 修" +- [ ] frontmatter `status: confirmed` + +--- + +## 退出后 + +告诉用户："根因分析已就绪，方案已确认。下一步阶段 3 修复验证，进入 `cs-issue` fix 阶段。" + +别自己顺手改代码——跨阶段无停顿往下跑会让用户来不及把关。 + +--- + +## 容易踩的坑 + +- 根因写"可能是某处的问题"——必须定位到 file:line +- 没读代码就靠问题描述推断——一定要实际 Grep / Read +- 只列一种修复方案——至少两种 +- 分析完直接开始改代码——必须等用户确认 +- 影响面写"可能影响其他功能"——要具体说哪些 +- 严重程度复核总是"维持"——认真看影响面，升级的要改 diff --git a/plugins/codestable/skills/cs-issue/references/fix/protocol.md b/plugins/codestable/skills/cs-issue/references/fix/protocol.md new file mode 100644 index 0000000..0091c61 --- /dev/null +++ b/plugins/codestable/skills/cs-issue/references/fix/protocol.md @@ -0,0 +1,161 @@ +# Issue Fix Protocol + +根因和方案已经确定（标准路径在 analysis、快速通道在 report 阶段口头确认过），你的活是按方案改代码、验证效果、写下修复记录。 + +fix 阶段最容易出问题的不是改代码本身，而是**改的过程中冒出的"顺手"冲动**——顺手优化、顺手重构、顺手加抽象。每项单独看说得通，但合在一个 PR 里让别人分不清"这次到底为了修 bug 改了什么"。 + +> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md` 第 0 节和 `cs-issue` 的"文件放哪儿"。 + +## 执行 gate（worktree + commit） + +进入修复前运行 start gate，`{slug}` 为 issue 目录名： + +```bash +python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/issues/YYYY-MM-DD-{slug} +``` + +gate 不通过就不要开始改代码；用户批准 override 时先在 unit 目录写 `worktree-override.md`（reason / scope / approval）。 + +修复完成、输出汇报前运行 commit gate： + +```bash +python3 .codestable/tools/codestable-worktree-gate.py --root . --json commit --unit .codestable/issues/YYYY-MM-DD-{slug} +``` + +gate 不通过就先处理 findings，不把"测试已过"当成完成。gate 工具的安装与 branch-guard hook 说明见 `.codestable/reference/branch-guard-hooks.md`。 + +--- + +## 两种入口 + +### 标准路径（有 analysis） + +1. **方案已确认**——读 analysis，确认 `doc_type=issue-analysis` 且 `status=confirmed`，第 5 节用户选定了哪个方案 +2. **上下文读全**：analysis 全文 + report 全文 + analysis 第 1 节定位的所有代码 + `.codestable/attention.md` + 沉淀目录搜索： + - `grep -r "{关键词}" .codestable/compound/`——确认修复方式不违背已有库用法 / 模式 / 调研结论 +3. **确认起点**——告诉用户"我将按方案 X 修改 {文件列表}，开始修复"，等用户确认才动手 + +### 快速通道（无 analysis，从 report 直接触发） + +进入这个入口时 AI 在 report 阶段已读过代码并对根因有把握。 + +1. **明确陈述根因**："`{文件}:{行号}` 的 {具体代码} 存在 {问题描述}"，让用户确认根因判断准确 +2. **给修复方案**——改哪里、怎么改（一两句话，不写完整分析文档） +3. **等用户明确说"对，就这样改"才动手**——不允许"我觉得对，直接改了" +4. 读 `.codestable/attention.md` +5. **补搜沉淀目录**——快速通道也要查一遍 `compound/`（trick + explore），避免误把已知边界条件当新问题 + +--- + +## 实现期间的约束 + +先做 `shared-conventions.md` 第 7 节的**第一性原则 pre-pass**：外部行为就是"复现路径不再失败"，约束来自 report / analysis / fix 方案，最小充分改动只服务根因；从这三项推不出的抽象、兜底和顺手重构都不写。 + +### 只改 analysis 里声明的文件 + +修复范围来自 analysis 第 5 节"推荐方案"的"影响面"。超出范围的文件——哪怕顺眼——**不动**。 + +发现范围外值得改的记一条"顺手发现"不改代码： + +```markdown +> 顺手发现：{文件:行号} {问题简述}。不在本次修复范围，可后续另开 issue。 +``` + +为什么这么严：顺手改的代码不在分析里，验收对不上，git blame 分不清哪些改动是为这个 bug。 + +### 改动最小化 + +修复只针对根因，**不引入新抽象、新接口、新模式**。如果发现"要把这个改好得先重构 X"——停下来跟用户确认是否在这个 issue 里做重构，还是拆成独立工作。 + +为什么：bug 修复天然窄场景，引入新抽象意味着只有这一个使用点支撑——典型过早抽象。 + +### 代码质量反射检查 + +修 bug 看似动作小但 AI 写修复代码一样会漂——大文件再塞特殊处理、大类再加方法、为绕开边界加 `if` 分支。反射检查见 `shared-conventions.md` 第 7 节。 + +issue-fix 比 feature-implement 更谨慎：**触发反射信号但结论是"该拆"时默认不在本次 PR 做**——按"改动最小化"记成顺手发现。唯一例外是"不拆就没法干净修这个 bug"，那停下来跟用户确认"修这个 bug 的前置是 {重构动作}，合进来还是拆出去单独做"。 + +### 每完成一处改动必须汇报 + +修复汇报模板见同目录 `reference.md`，**不允许含糊汇报**。汇报后停下等用户回复。 + +--- + +## 验证清单 + +修复改完后逐项核对： + +- [ ] **复现步骤验证**——按 report 第 2 节走一遍，问题不再出现 +- [ ] **期望行为验证**——report 第 3 节"期望行为"现在确实发生 +- [ ] **影响面回归**——analysis 第 4 节"潜在受害模块"每个走一遍最基本的冒烟路径 +- [ ] **前端改动浏览器验证**（如涉及）——按 `.codestable/attention.md` 的硬要求执行，不能只 typecheck +- [ ] **相关测试通过**——有测试覆盖到修复区域就跑一遍 + +--- + +## 修复未生效时：日志调试升级 + +走完验证清单仍**问题复现**或行为与期望不符——**别在原有猜测上反复试错**，切换到日志调试模式重新收集运行时证据。 + +为什么切换：反复试错本质是猜测在原假设下还有什么可能性，但如果原假设就错了再猜也是绕圈。日志强制看实际运行时数据，往往一眼看出原假设哪里偏了。 + +日志调试步骤、用户取日志提示词、循环限制见同目录 `reference.md`。 + +--- + +## 写 {slug}-fix-note.md + +验证通过后在 issue 目录建 `{slug}-fix-note.md`（位置见 `cs-issue` 的"文件放哪儿"），记录完整闭环。标准路径模板和快速通道模板都在同目录 `reference.md`。 + +--- + +## 退出条件 + +- [ ] 所有改动文件已提交或列清单 +- [ ] 验证清单全部勾选 +- [ ] `{slug}-fix-note.md` 已建并填写完整 +- [ ] 没有未处理的"顺手发现"（都进后续 issue 列表） +- [ ] 没有范围外改动（或已和用户确认） +- [ ] 用户明确确认修复完成 + +--- + +## 收尾提交 + +按 `shared-conventions.md` 第 4 节"scoped-commit"规则执行。本阶段： + +- **提交范围**：修复代码 + `{slug}-fix-note.md` + 本次一并更新的 report / analysis +- 修复闭环后告诉用户"修复验证已完成，`{slug}-fix-note.md` 已落盘"，紧接着问是否需要 commit + +--- + +## 退出后 + +告诉用户："issue 修复完成，工作流闭环。report + analysis + fix-note 已存档。" + +按 `shared-conventions.md` 第 3 节"issue-fix"收尾推荐顺序各问一句（用户"不用"立即跳过）： + +0. 完成后先进入 `cs-code-review` 做独立 diff 评审；Critical/Important 未清零不进 commit，scoped-commit 发起权归 `cs-code-review`。 +1. 暴露的坑点 / 长期约束 / 规约 / 技术决定 → "沉淀到 compound？（`cs-keep`）" +2. 这个 bug 暴露了项目通用的硬约束 / 命令陷阱 / 环境设置（一两行能讲清、CodeStable 技能每次启动都该知道）→ "记到 attention.md？（`cs-note`）" +3. 最后问是否代为提交。同意时按收尾提交规则执行 + +建议：把 issue 目录文件和代码改动放同一次提交方便追溯；"顺手发现"另开 `cs-issue` report 阶段 处理别塞这个 PR。 + +修复中发现问题实际是功能缺失（不是 bug）→ 建议另开 `cs-feat`，别在 issue 工作流里偷偷做新功能。 + +--- + +## 容易踩的坑 + +- 修完没走验证清单就宣告"修好了" +- 顺手改了 analysis 范围外的代码 +- 修复引入新抽象 / 接口但没停下来确认 +- `{slug}-fix-note.md` 没建就宣告完成 +- 发现影响面回归有问题但写"轻微影响可忽略"——要修到干净 +- 前端改动只 typecheck 就报通过 +- 用户没明确说"修复完成"就结束 +- 修复未生效继续原假设上反复猜测试错，不切换到日志调试 +- 日志调试结束后没清理临时 log 就提交 +- 收尾时没问用户是否代为 commit +- 用户没明确同意就 `git commit` diff --git a/plugins/codestable/skills/cs-issue-fix/reference.md b/plugins/codestable/skills/cs-issue/references/fix/reference.md similarity index 91% rename from plugins/codestable/skills/cs-issue-fix/reference.md rename to plugins/codestable/skills/cs-issue/references/fix/reference.md index 21f39cc..74b5793 100644 --- a/plugins/codestable/skills/cs-issue-fix/reference.md +++ b/plugins/codestable/skills/cs-issue/references/fix/reference.md @@ -1,6 +1,6 @@ # issue-fix 参考模板 -本文件提供 `cs-issue-fix` 使用的修复汇报模板、日志调试脚手架和 `{slug}-fix-note.md` 模板。 +本文件提供 `cs-issue` fix 阶段 使用的修复汇报模板、日志调试脚手架和 `{slug}-fix-note.md` 模板。 ## 1. 修复汇报模板 @@ -37,7 +37,7 @@ 5. 清理日志打点 6. 以修订后的根因重新进入修复流程 -如果经过 2 轮日志调试仍未定位到根因，建议回到 `cs-issue-analyze`。 +如果经过 2 轮日志调试仍未定位到根因，建议回到 `cs-issue` analyze 阶段。 ### 用户取日志提示词 diff --git a/plugins/codestable/skills/cs-issue/references/report/protocol.md b/plugins/codestable/skills/cs-issue/references/report/protocol.md new file mode 100644 index 0000000..cd35c44 --- /dev/null +++ b/plugins/codestable/skills/cs-issue/references/report/protocol.md @@ -0,0 +1,145 @@ +# Issue Report Protocol + +这一阶段做两件事：把用户脑子里的问题落成结构化记录 + 判断走标准路径还是快速通道。 + +**核心原则：只记现象不记根因**。用户说"我觉得是 XX 组件的问题"——记下"用户怀疑 XX 组件"作为线索，但不顺着聊根因。根因要在阶段 2 通过实际读代码确认，不靠脑子里猜。混进根因猜测的报告会带偏阶段 2，让分析人围着错误线索绕。 + +> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md` 第 0 节和 `cs-issue` 的"文件放哪儿"。 + +--- + +## 启动检查 + +1. **确认是 bug 不是新功能需求**——描述"想加 X 功能"的告诉他走 `cs-feat` +2. **看有没有相关 issue 目录**——Glob `.codestable/issues/`，有同类问题先和用户确认是新建还是更新 +3. **快速通道判断（唯一正式判定点）**——按用户线索**读一下相关代码**（Grep / Read 定位）： + - **能一眼确定根因**（能给出 `{文件}:{行号}`、修复改动小 1-2 处、无跨模块影响风险）→ 告诉用户"我已看到问题所在，可以走快速通道：直接告知根因和修复方案，你确认后我立刻修，修完你验证，只写一份 `{slug}-fix-note.md`"。同意后进入 `cs-issue` fix 阶段（快速通道模式） + - **不能**（根因有多个候选 / 不确定 / 需要更多复现信息）→ 走标准路径做完整问题报告。进入标准路径后默认不再二次改判 +4. **确定 issue 目录名**——跟用户商定 slug，日期前缀用今天（环境信息 `currentDate`）。目录不存在就创建。快速通道也要建 issue 目录，`{slug}-fix-note.md` 放那 + +--- + +## 必答 5 问 + +按顺序逐个问，**不一次抛 5 个**——一次抛多个用户只回最容易的，深的就漏了。每问做一次模糊度检查，不通过继续追问。 + +### 1. 问题是什么？看到的现象？ + +期待具体的异常表现："点击提交按钮后弹出了空白弹窗" 比 "提交功能有问题" 有用一百倍。 + +模糊信号："有时候会出错"、"感觉不对" → 追问"具体什么时候"、"具体什么不对"。 + +红线：**不要让用户描述根因**。出现"应该是因为 XXX"——记现象，根因留给阶段 2。 + +### 2. 怎么复现？ + +期待最小复现步骤：进入 XX 页面 → 输入 YY → 点击 ZZ → 看到问题现象。 + +模糊信号："不稳定复现"、"有时候能有时候不能" → 追问复现频率和条件差异。确实不稳定就写明已知触发条件和复现率。 + +"无法复现"也是有效回答——写"目前无法稳定复现，只在 X 情况下观察到一次"，别勉强凑步骤。 + +### 3. 期望行为 vs 实际行为 + +期待两句话： +- **期望**：我以为做了 A 之后应该发生 B +- **实际**：但实际发生了 C + +**不要合并成一句**。合在一句"按钮没正常工作"里分析的人不知道"正常"长什么样。 + +### 4. 环境信息 + +最低采集：**在哪个模块 / 功能区域发现的**、**相关文件或函数（用户知道的话）**。 + +可选：操作系统、浏览器版本、运行环境（dev / prod）、最近有没有改过相关代码。 + +用户说"不知道在哪个文件"——写"待定"，阶段 2 分析时查。 + +### 5. 严重程度与优先级 + +- **P0 阻塞**：核心功能完全失效，影响所有用户，必须立刻修 +- **P1 严重**：核心功能受损有绕过方法，尽快修 +- **P2 中等**：非核心功能或影响少数用户，计划内修 +- **P3 轻微**：UI 瑕疵 / 边界情况 / 有更好实现，按空闲修 + +用户不确定就帮他推荐一个但让用户拍板。 + +--- + +## 问题报告模板 + +```markdown +--- +doc_type: issue-report +issue: {issue 目录名} +status: draft +severity: P0 | P1 | P2 | P3 +summary: {问题现象一句话} +tags: [] +--- + +# {问题简述} Issue Report + +## 1. 问题现象 + +{用户描述的具体异常表现，纯现象描述，不含根因推测} + +## 2. 复现步骤 + +1. {步骤 1} +2. {步骤 2} +3. 观察到：{问题现象} + +复现频率：{稳定 / 概率（约 X%） / 暂无法稳定} + +## 3. 期望 vs 实际 + +**期望行为**：{做了 A 应该发生 B} + +**实际行为**：{但实际发生了 C} + +## 4. 环境信息 + +- 涉及模块 / 功能：{模块名或功能描述} +- 相关文件 / 函数：{已知 file:line 或"待定"} +- 运行环境：{dev / staging / prod / 不确定} +- 其他上下文：{OS、浏览器、最近改动等，没有写"无"} + +## 5. 严重程度 + +**{P0 / P1 / P2 / P3}** — {一句话理由} + +## 备注 + +{可选：截图描述、日志片段等} +``` + +--- + +## 退出条件 + +- [ ] frontmatter 完整（`doc_type=issue-report` / `issue` 一致 / `severity` 和 `summary` 非空 / `tags` ≥ 1） +- [ ] 5 问都有具体答案（环境中相关文件可"待定"） +- [ ] 问题现象是纯现象描述，没混入根因推测 +- [ ] 期望 vs 实际显式分开写 +- [ ] 复现步骤可执行（"无法稳定复现"也有说明） +- [ ] 用户明确说"report 可以了，进下一步" +- [ ] frontmatter `status: confirmed` + +--- + +## 退出后 + +告诉用户："问题报告已就绪。下一步阶段 2 根因分析，进入 `cs-issue` analyze 阶段。" + +别自己顺手开始分析根因——阶段间的人工 checkpoint 是工作流硬约束。 + +--- + +## 容易踩的坑 + +- 用户说"可能是 XX 的问题"你顺着聊根因——错，那是阶段 2 +- 复现步骤太模糊（"在用户界面操作一下"）就放行——逼出可执行步骤 +- 期望和实际混在一段话里——必须显式分开 +- 严重程度留空——给默认值或写"无" +- 一口气把 5 问列成清单丢给用户填——逐题对话否则深的全漏 diff --git a/plugins/codestable/skills/cs-onboard/SKILL.md b/plugins/codestable/skills/cs-onboard/SKILL.md index c4f6d58..1ea863d 100644 --- a/plugins/codestable/skills/cs-onboard/SKILL.md +++ b/plugins/codestable/skills/cs-onboard/SKILL.md @@ -22,7 +22,7 @@ description: CodeStable 接入。触发：初始化/迁移/搭骨架，自动判 ## 标准骨架（目标状态） -> 共享路径与命名约定的权威版本是项目里的 `.codestable/reference/shared-conventions.md`——本技能从技能包复制过去。下面只列 onboard 创建 / 检查的骨架文件。 +> 共享路径与命名约定的权威版本是项目里的 `.codestable/reference/shared-conventions.md`——本技能从技能包内 `references/` 复制过去。下面只列 onboard 创建 / 检查的骨架文件。 ``` .codestable/ @@ -89,7 +89,7 @@ description: CodeStable 接入。触发：初始化/迁移/搭骨架，自动判 - `.codestable/attention.md`（最小骨架模板见同目录 `reference.md`） - `.codestable/gates/`（用 `cp -rf` / `Copy-Item -Recurse -Force` 整目录拷贝当前 `cs-onboard` skill 目录的 `gates/`） - `.codestable/tools/`（用 `cp -rf` / `Copy-Item -Recurse -Force` 整目录拷贝当前 `cs-onboard` skill 目录的 `tools/`，**不要 Read 再 Write**） -- `.codestable/reference/`（同上） +- `.codestable/reference/`（从当前 `cs-onboard` skill 目录的 `references/` 整目录复制） - `.codestable/hooks/`（同上；可选的分支保护层，见下文「分支保护 hook」） `requirements/CONTEXT.md` 和 `requirements/adrs/` 不在骨架里——交给 `cs-domain` 在用户第一次需要术语 / ADR 时 lazy 创建。 @@ -139,7 +139,7 @@ attention.md 已创建但默认只有空骨架。汇报时提醒用户：有编 对照标准骨架补齐**用户确认后仍缺失**的目录 / 文件。已有内容不覆盖。 -**`.codestable/gates/`、`.codestable/tools/` 和 `.codestable/reference/` 一律用技能包新版本覆盖**——这些目录是技能包维护的共享资产，权威源在当前 `cs-onboard` skill 目录的 `gates/`、`tools/` 和 `reference/`，项目里的只是落盘副本。技能包升级后再跑 onboard 的目的之一就是刷新副本，留旧版本会让子技能按过时口径工作。 +**`.codestable/gates/`、`.codestable/tools/` 和 `.codestable/reference/` 一律用技能包新版本覆盖**——这些目录是技能包维护的共享资产，权威源在当前 `cs-onboard` skill 目录的 `gates/`、`tools/` 和 `references/`；项目里的只是落盘副本，且运行时目录名固定为 `.codestable/reference/`。技能包升级后再跑 onboard 的目的之一就是刷新副本，留旧版本会让子技能按过时口径工作。 覆盖前在汇报列出被覆盖文件让用户知道；用户明确说"我改过 tools/xxx.py 请保留"才例外保留并标红。这是迁移路径**唯一强制覆盖**的动作，其他已有文件遵守"不经确认不动"。 @@ -149,7 +149,7 @@ attention.md 已创建但默认只有空骨架。汇报时提醒用户：有编 # macOS / Linux cp -rf /gates/. .codestable/gates/ cp -rf /tools/. .codestable/tools/ -cp -rf /reference/. .codestable/reference/ +cp -rf /references/. .codestable/reference/ cp -rf /hooks/. .codestable/hooks/ cp -f /codestable.gitignore .codestable/.gitignore find .codestable/tools -type d -name __pycache__ -prune -exec rm -rf {} + @@ -158,7 +158,7 @@ find .codestable/tools -type f -name '*.pyc' -delete # Windows PowerShell Copy-Item -Recurse -Force \gates\* .codestable\gates\ Copy-Item -Recurse -Force \tools\* .codestable\tools\ -Copy-Item -Recurse -Force \reference\* .codestable\reference\ +Copy-Item -Recurse -Force \references\* .codestable\reference\ Copy-Item -Recurse -Force \hooks\* .codestable\hooks\ Copy-Item -Force \codestable.gitignore .codestable\.gitignore Remove-Item -Recurse -Force .codestable\tools\__pycache__ -ErrorAction SilentlyContinue diff --git a/plugins/codestable/skills/cs-onboard/reference/system-overview.md b/plugins/codestable/skills/cs-onboard/reference/system-overview.md deleted file mode 100644 index d923c3e..0000000 --- a/plugins/codestable/skills/cs-onboard/reference/system-overview.md +++ /dev/null @@ -1,109 +0,0 @@ -# CodeStable 体系总览 - -本文档介绍 CodeStable 工作流家族整体——有哪些子技能、各管什么场景、产物怎么组织。无论是 AI 在运行时读到这个文件，还是人打开来看，都能对整个体系有个完整印象。 - -AI 辅助开发里，有几类场景会反复出现——加新功能、修 bug、遇到值得沉淀的经验、做技术选型、摸新模块的代码、接入新仓库。每种场景如果每次从零处理，都会出各自的典型问题：AI 给功能起的术语跟老代码冲突、bug 改完没人记得当时怎么诊断的、上周刚踩过的坑下周又踩一遍。 - -CodeStable 把这几类场景各配一套子技能，产物放进统一的目录结构、带统一的 YAML frontmatter,互相之间可以检索引用。 - - -## 技能分成四部分 - -**根入口**——开放式诉求 / 不知道走哪个时的统一入口: - -- `cs` — 介绍体系全貌 + 把诉求路由到正确的 cs-* 子技能。本技能不做事,只做分诊和提示 - -**做事**——从一段模糊想法走到上线的功能、或者从一份错误报告走到修好的 bug: - -- `cs-feat` — 新功能,design → design-review → implement → code-review → QA → acceptance（想法还模糊时先走讨论层 `cs-brainstorm` 做分诊，不属于 feature 流程内部） -- `cs-goal` — 目标达成,限定起点/终点 → interview/grill 写起点报告 → 自主迭代实现/验证 → 完成前 Task agent 功能验收 -- `cs-issue` — 修 bug,report → analyze → fix -- `cs-refactor` — 代码优化(行为不变、结构/性能/可读性变),scan → design → apply -- `cs-code-review` — 各执行流末端、commit 前的横切独立 diff 评审（质量门禁） - -两类都不直接让 AI 写代码,而是先产出 spec(功能方案 / 问题分析),用户 review 后再动手,代码和 doc 一起交付。针对的是术语冲突、范围失控、改完不留存档这三种 AI 默认会出的问题。 - -**沉淀**——把做事过程产生的知识存下来,下次遇到同类问题直接复用: - -- `cs-keep` — 把坑点 / 技巧 / 决策 / 调研沉淀到 `.codestable/compound/`，纯 markdown，grep 检索 -- `cs-note` — 把一两行启动必读的项目注意事项追加到 `.codestable/attention.md` - -**讨论层**——想法还模糊时的统一入口,不直接产出设计或代码: - -- `cs-brainstorm` — 和用户对话做分诊:case 1(已经够清楚,直接 feature-design)、case 2(小需求,在 feature 里继续讨论并落 `{slug}-brainstorm.md`)、case 3(大需求,移交给 roadmap) - -**辅助**——围着前几类转的周边工具: - -- `cs-onboard` — 把新仓库接入 CodeStable 目录结构 -- `cs-req` — 起草或刷新 `.codestable/requirements/` 下的需求文档——系统的能力愿景层，覆盖过去/现在/未来 -- `cs-domain` — 领域模型一站式：CONTEXT.md 术语维护 + ADR 决策记录（守门 3 判据 + Nygard 四节）+ 单/多 context 拓扑管理 -- `cs-roadmap` — 把一块装不进单个 feature 的大需求拆成带依赖和状态的子 feature 清单,作为后续多次 feature 流程的种子和排期依据;独立于需求 / 架构档案 -- `cs-roadmap-review` — roadmap 人工确认前的只读规划审查 gate -- `cs-roadmap-impl-goal` — 把已确认 roadmap 编排成可直接运行的 goal,逐个 feature 衔接 design / impl / review / QA / accept -- `cs-feat-design-review` — feature design 人工确认前的只读方案审查 gate -- `cs-doc-tutorial` — 写给外部读者的开发者指南 / 用户指南（任务导向） -- `cs-doc-api` — 为公开 API 逐条目生成参考文档（从源码反推） -- `cs-docs-neat` — 阶段 / 里程碑收尾时，全局整理 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆，做反膨胀、补漏和冲突修正 -- `codestable-maintainer` — 维护 CodeStable 自身技能库 / harness / verifier / installed copy（源仓分支验证 + main-only 同步） - - -## 场景路由 - -仓库里还没有 `.codestable/` 目录,先用 `cs-onboard` 搭骨架。 - -| 场景 | 子技能 | -|---|---| -| 想法还模糊 / "有个想法没想清楚" / "先聊聊" | `cs-brainstorm`(分诊后路由到 design / feature-brainstorm 落盘 / roadmap) | -| 新功能 / 新能力 | `cs-feat` | -| 限定起点/终点的目标达成 / "自主迭代直到完成" | `cs-goal` | -| BUG / 异常 / 文档错误 | `cs-issue` | -| 代码优化 / 重构 / 重写(行为不变) | `cs-refactor` | -| 合并前代码评审 / "code review" / 准备 PR / merge | `cs-code-review` | -| 摸代码、提问调研 / 踩坑回顾 / 技术选型沉淀 / 可复用模式 | `cs-keep` | -| 补 / 更新需求文档 | `cs-req` | -| 拍板技术决策 / 加术语 / 项目要分子系统 | `cs-domain` | -| 大需求拆解 / 排期规划 | `cs-roadmap` | -| roadmap 人审前规划审查 | `cs-roadmap-review` | -| 推进已有 roadmap / 执行整个 roadmap | `cs-roadmap-impl-goal` | -| feature design 人审前方案审查 | `cs-feat-design-review` | -| 开发者指南 / 用户指南 | `cs-doc-tutorial` | -| 库 API 参考 | `cs-doc-api` | -| 阶段收尾 / 整理文档 / 同步 agent 入口 / 新人交接 | `cs-docs-neat` | - -完整的操作手册、退出条件、和其他工作流的关系,各子技能里讲。 - - -## 愿景档案 vs 结构档案 vs 规划档案 vs 单次动作 - -四类文档各管一段时间尺度,不要混: - -- **愿景档案**(requirements)——描述"用户需要什么、系统提供什么能力来满足"。`status` 区分三个时间深度：`draft`（未来愿景）、`current`（现在的能力）、`outdated`（过去的痕迹）。draft req 可独立于实现存在——先把愿景定下来，后续 roadmap 排期和 design 实现才有稳定对齐基准 -- **领域档案**(CONTEXT.md / adrs/)——描述"项目用什么术语、为什么做出这些结构性决策"。术语跟着 capability 引入；ADR 严格 3 判据，不每个决定都记。cs-domain 维护 -- **规划档案**(roadmap)——描述"接下来打算怎么分步实现"。独立于愿景和领域档案,改动不牵连 requirements。所有条目 done / dropped 后 roadmap 进入 `completed` 状态,作为历史档案留存 -- **单次动作**(feature / issue / refactor)——本次要做的一件具体事情的 spec。动作走完后,相关沉淀提炼进愿景档案、结构档案和 compound - -用户说"我想要一个 X 系统"这种大需求,先走 roadmap 拆成若干子 feature,再一条一条走 feature 流程。直接起 feature 会变成巨型 design 塞不下、拆了又没有追踪抓手。 - - -## feature 和 issue 的阶段不可跳 - -feature 走 brainstorm(可选) → design → design-review → implement → code-review → QA → acceptance,issue 走 report → analyze → fix。每个阶段有退出条件,上一个没满足,下一个不开始。 - -AI 最常见的问题是一口气铺几百行代码才让人看——等发现问题已经很难中止。阶段间的人工 checkpoint 就是为了早一步中止。每个 checkpoint 具体检查什么,对应子技能里讲。 - -例外两种:issue 根因一眼确定时走快速通道,跳过 analyze 直接 fix;feature 范围小时走 `cs-feat-ff`,写完 spec 直接进实现。 - - -## 进一步参考 - -- `.codestable/reference/shared-conventions.md` — 目录结构、YAML frontmatter 口径、`{slug}-checklist.yaml` 生命周期、收尾 commit 约定、cs-keep 守护规则 -- `.codestable/reference/tools.md` — `search-yaml.py` / `validate-yaml.py` 用法（compound 不用这俩，直接 grep） -- `.codestable/reference/maintainer-notes.md` — 断点恢复、新增子工作流的登记 - -目录结构(requirements/、roadmap/、features/、issues/、compound/、tools/、reference/)的权威定义在 `shared-conventions.md`。要改目录先改那里——方法是改 `plugins/codestable/skills/cs-onboard/reference/shared-conventions.md` 这个模板,新项目 onboard 时会带上新版本。 - - -## 相关 - -- `.codestable/attention.md` — CodeStable 技能启动必读的项目注意事项 -- `.codestable/requirements/CONTEXT.md` — 项目领域术语表（cs-domain，lazy 创建） diff --git a/plugins/codestable/skills/cs-onboard/reference/approval-conventions.md b/plugins/codestable/skills/cs-onboard/references/approval-conventions.md similarity index 95% rename from plugins/codestable/skills/cs-onboard/reference/approval-conventions.md rename to plugins/codestable/skills/cs-onboard/references/approval-conventions.md index b404034..522bc0a 100644 --- a/plugins/codestable/skills/cs-onboard/reference/approval-conventions.md +++ b/plugins/codestable/skills/cs-onboard/references/approval-conventions.md @@ -12,10 +12,10 @@ report。 canonical stage report 如果已经包含 decision、options、recommendation、tradeoffs、 evidence、consequence 和 next action，就可以满足此规则。例如： -- `cs-feat-design` design review; -- `cs-issue-analyze` fix-option analysis; -- `cs-issue-fix` fix-note / implementation review; -- `cs-feat-accept` acceptance report. +- `cs-feat` design review; +- `cs-issue` fix-option analysis; +- `cs-issue` fix-note / implementation review; +- `cs-feat` acceptance report. 如果不存在这样的 stage report，写： diff --git a/plugins/codestable/skills/cs-onboard/reference/branch-guard-hooks.md b/plugins/codestable/skills/cs-onboard/references/branch-guard-hooks.md similarity index 100% rename from plugins/codestable/skills/cs-onboard/reference/branch-guard-hooks.md rename to plugins/codestable/skills/cs-onboard/references/branch-guard-hooks.md diff --git a/plugins/codestable/skills/cs-onboard/reference/code-dimensions.md b/plugins/codestable/skills/cs-onboard/references/code-dimensions.md similarity index 100% rename from plugins/codestable/skills/cs-onboard/reference/code-dimensions.md rename to plugins/codestable/skills/cs-onboard/references/code-dimensions.md diff --git a/plugins/codestable/skills/cs-onboard/reference/execution-conventions.md b/plugins/codestable/skills/cs-onboard/references/execution-conventions.md similarity index 100% rename from plugins/codestable/skills/cs-onboard/reference/execution-conventions.md rename to plugins/codestable/skills/cs-onboard/references/execution-conventions.md diff --git a/plugins/codestable/skills/cs-onboard/reference/goal-conventions.md b/plugins/codestable/skills/cs-onboard/references/goal-conventions.md similarity index 100% rename from plugins/codestable/skills/cs-onboard/reference/goal-conventions.md rename to plugins/codestable/skills/cs-onboard/references/goal-conventions.md diff --git a/plugins/codestable/skills/cs-onboard/reference/maintainer-notes.md b/plugins/codestable/skills/cs-onboard/references/maintainer-notes.md similarity index 95% rename from plugins/codestable/skills/cs-onboard/reference/maintainer-notes.md rename to plugins/codestable/skills/cs-onboard/references/maintainer-notes.md index 4c3e8ba..5695a08 100644 --- a/plugins/codestable/skills/cs-onboard/reference/maintainer-notes.md +++ b/plugins/codestable/skills/cs-onboard/references/maintainer-notes.md @@ -23,7 +23,7 @@ AI 对话随时可能中断（token 超限、网络断开、用户换设备） ### 新增子工作流 -新工作流定型后，在 `plugins/codestable/skills/cs-onboard/reference/system-overview.md` 的"技能分成四部分"和"场景路由"表里加一段索引，并登记新的目录位置。 +新工作流定型后，在 `plugins/codestable/skills/cs-onboard/references/system-overview.md` 的"技能分成四部分"和"场景路由"表里加一段索引，并登记新的目录位置。 ### 跨阶段新约束 diff --git a/plugins/codestable/skills/cs-onboard/reference/requirement-example.md b/plugins/codestable/skills/cs-onboard/references/requirement-example.md similarity index 100% rename from plugins/codestable/skills/cs-onboard/reference/requirement-example.md rename to plugins/codestable/skills/cs-onboard/references/requirement-example.md diff --git a/plugins/codestable/skills/cs-onboard/reference/shared-conventions.md b/plugins/codestable/skills/cs-onboard/references/shared-conventions.md similarity index 85% rename from plugins/codestable/skills/cs-onboard/reference/shared-conventions.md rename to plugins/codestable/skills/cs-onboard/references/shared-conventions.md index da6e788..dd5211e 100644 --- a/plugins/codestable/skills/cs-onboard/reference/shared-conventions.md +++ b/plugins/codestable/skills/cs-onboard/references/shared-conventions.md @@ -26,7 +26,7 @@ onboard 完成后骨架（`cs-onboard` 负责搭建）： │ ├── adrs/ 子 context 特定 ADR │ └── {capability}.md 归属本 context 的能力 ├── roadmap/ 规划层（"接下来怎么做这块大需求 + 模块怎么切 + 接口怎么定"） -│ └── {slug}/ 一个大需求一个子目录（cs-roadmap 产出） +│ └── {slug}/ 一个大需求一个子目录（cs-epic 产出） │ ├── {slug}-roadmap.md 主文档：背景 / 范围 / 模块拆分 / 接口契约 / 子 feature 清单 / 排期 │ ├── {slug}-items.yaml 机器可读子 feature 清单，acceptance 回写状态 │ ├── {slug}-roadmap-review.md 人工确认前的规划审查报告 @@ -86,13 +86,13 @@ onboard 完成后骨架（`cs-onboard` 负责搭建）： ### 改目录结构 -改 `plugins/codestable/skills/cs-onboard/reference/shared-conventions.md` 模板，新项目 onboard 时带上新版本；已有项目手动同步 `.codestable/reference/shared-conventions.md`。 +改 `plugins/codestable/skills/cs-onboard/references/shared-conventions.md` 模板，新项目 onboard 时带上新版本；已有项目手动同步 `.codestable/reference/shared-conventions.md`。 --- ## 1. 共享元数据口径 -**feature spec**：brainstorm / design / design-review / review / QA / acceptance 共用 `doc_type` / `feature` / `status` / `summary` / `tags`。子技能只补特有字段。`status`：brainstorm = `confirmed`（落盘即确认无 draft）；design = `draft` / `approved`；design-review / review / QA / acceptance 见对应技能。 +**feature spec**：brainstorm / design / design-review / review / QA / acceptance 共用 `doc_type` / `feature` / `status` / `summary` / `tags`。`cs-feat` 的各阶段只补特有字段。`status`：brainstorm = `confirmed`（落盘即确认无 draft）；design = `draft` / `approved`；design-review / review / QA / acceptance 见对应阶段协议。 新增 feature gate 的 `doc_type`：`feature-design-review`（status: `passed` / `changes-requested` / `blocked`）、`feature-review`（status: `passed` / `changes-requested` / `blocked`）、`feature-qa`（status: `passed` / `failed` / `blocked`）、`feature-acceptance`（status: `passed` / `blocked`）。review / QA 报告是后续 gate 的输入，不替用户批准 design，也不替 acceptance 做最终验收。 @@ -100,7 +100,7 @@ onboard 完成后骨架（`cs-onboard` 负责搭建）： **归档类（compound）**：由 `cs-keep` 统一产出，写到 `.codestable/compound/YYYY-MM-DD-{slug}.md`。纯 markdown，**无 frontmatter**。三段足够：背景 / 结论 / 证据。检索靠 grep。 -**外部读者文档**（cs-doc-tutorial / cs-doc-api）：frontmatter 由各自子技能定义。无特殊说明：`draft` = 待 review，`current` = 当前有效，`outdated` = 代码已变更待同步。 +**外部读者文档**（`cs-docs` tutorial / api mode）：frontmatter 由对应模式定义。无特殊说明：`draft` = 待 review，`current` = 当前有效，`outdated` = 代码已变更待同步。 **写作约束**：子技能提字段时优先写"额外字段"或"阶段状态变化"，不重复展开整套通用字段。 @@ -109,8 +109,8 @@ onboard 完成后骨架（`cs-onboard` 负责搭建）： ## 2. {slug}-checklist.yaml 生命周期 - 是 feature 工作流的唯一执行清单 -- 由 `cs-feat-design` 在 draft design 成型后先生成 `steps` + `checks`，供 `cs-feat-design-review` 和用户 review；用户确认后随 design 一起进入实现 -- `cs-feat-ff` **不生成** checklist（也不写 design / acceptance），是跳过 spec 流程直接写代码的超轻量通道；唯一留下的痕迹是动手后回写的 `{slug}-ff-note.md`（轻量回顾，参与 scoped-commit、可被 cs-req / cs-domain backfill 检索到） +- 由 `cs-feat` design 阶段在 draft design 成型后先生成 `steps` + `checks`，供 design-review 阶段和用户 review；用户确认后随 design 一起进入实现 +- `cs-feat` fastforward mode **不生成** checklist（也不写 design / acceptance），是跳过 spec 流程直接写代码的超轻量通道；唯一留下的痕迹是动手后回写的 `{slug}-ff-note.md`（轻量回顾，参与 scoped-commit、可被 cs-req / cs-domain backfill 检索到） `steps` 的粒度是 **编排-计算分离维度的切片策略**——按"先编排骨架、后计算节点、最后持久化与测试"写（最简 Workflow 先行 → 逐个节点填充），**不下沉到 file:line / 函数级**。具体改哪个文件由 implement 阶段决定。 @@ -138,28 +138,28 @@ onboard 完成后骨架（`cs-onboard` 负责搭建）： **items.yaml 状态机**： ``` -planned → in-progress （cs-feat-design 启动 feature 时改） -in-progress → done （cs-feat-accept 验收完成时改） -planned → dropped （cs-roadmap update 模式，用户决定不做时改） +planned → in-progress （cs-feat design 阶段启动 feature 时改） +in-progress → done （cs-feat acceptance 阶段验收完成时改） +planned → dropped （cs-epic planning update 模式，用户决定不做时改） ``` `done` / `dropped` 是终态。需要回退重做的新加一条 slug 略改的条目，不改终态。 -**cs-roadmap 的职责**：生成和维护 roadmap 主文档 + items.yaml；把 `planned` 改 `dropped`（用户放弃时）；不改 `in-progress` / `done`（feature 技能负责）。 +**cs-epic planning 阶段的职责**：生成和维护 roadmap 主文档 + items.yaml；把 `planned` 改 `dropped`（用户放弃时）；不改 `in-progress` / `done`（feature 流程负责）。第一版内部仍使用 `.codestable/roadmap/`。 -**cs-roadmap-review 的职责**：在人审前只读审查 roadmap 主文档 + items.yaml + 相关事实，写 `{slug}-roadmap-review.md`；不修改 roadmap，不替用户批准。 +**cs-epic review 阶段的职责**：在人审前只读审查 roadmap 主文档 + items.yaml + 相关事实，写 `{slug}-roadmap-review.md`；不修改 roadmap，不替用户批准。 -**cs-feat-design 的职责**（从 roadmap 起头时）： +**cs-feat design 阶段的职责**（从 roadmap 起头时）： 1. design.md frontmatter 加 `roadmap: {roadmap-slug}` + `roadmap_item: {子 feature slug}` 2. items.yaml 对应条目 `status: in-progress` + `feature: YYYY-MM-DD-{slug}` 3. 校验 yaml -**cs-feat-design-review 的职责**：在人审前只读审查 design + checklist + 相关事实，写 `{slug}-design-review.md`；不修改 design/checklist，不替用户批准。 +**cs-feat design-review 阶段的职责**：在人审前只读审查 design + checklist + 相关事实，写 `{slug}-design-review.md`；不修改 design/checklist，不替用户批准。 直接起 feature（非 roadmap 来）两字段留空，不触发 roadmap 写。 -**cs-feat-accept 的职责**： +**cs-feat acceptance 阶段的职责**： 1. 读 design frontmatter `roadmap` / `roadmap_item` 2. 空 → 跳过 @@ -176,8 +176,8 @@ planned → dropped （cs-roadmap update 模式，用户决定不做时改 **feature-acceptance** 收尾按顺序判断： 1. `cs-keep`：沉淀坑点 / 技巧 / 长期约束 / 选型 -2. `cs-doc-tutorial`：开发者 / 用户指南 -3. `cs-doc-api`：公开 API 参考 +2. `cs-docs` tutorial mode：开发者 / 用户指南 +3. `cs-docs` api mode：公开 API 参考 4. `cs-docs-neat`：阶段 / 里程碑收尾时同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 5. `scoped-commit` @@ -193,10 +193,10 @@ planned → dropped （cs-roadmap update 模式，用户决定不做时改 2. `cs-docs-neat`：快速改动影响 README/docs 或 agent 入口时同步 3. `scoped-commit` -**roadmap** 收尾按顺序判断： +**epic / roadmap** 收尾按顺序判断： 1. `cs-docs-neat`：roadmap 确认落盘或整个 roadmap goal 完成后，同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 -2. 后续若要自动推进整份 roadmap，再走 `cs-roadmap-impl-goal` +2. 后续若要自动推进整份 roadmap，再走 `cs-epic` goal-package 阶段 **统一规则**：一律一句话提示；用户说"不用"立即跳过；不强制；上游主动提示，下游承接执行。 @@ -240,7 +240,7 @@ feature-design / issue-analyze / issue-fix 动手前到 `.codestable/compound/` ## 7. 写代码时的反射检查 -`cs-feat-impl`、`cs-feat-ff`、`cs-issue-fix`、`cs-refactor-ff` 共用。AI 默认会往"大函数 / 大文件 / god class / 处处特殊分支"漂，这一节把漂移截在发生那一刻。 +`cs-feat` implementation / fastforward、`cs-issue` fix、`cs-refactor` apply / fastforward 共用。AI 默认会往"大函数 / 大文件 / god class / 处处特殊分支"漂，这一节把漂移截在发生那一刻。 ### 第一性原则 pre-pass diff --git a/plugins/codestable/skills/cs-onboard/reference/spec-governance-tools.md b/plugins/codestable/skills/cs-onboard/references/spec-governance-tools.md similarity index 100% rename from plugins/codestable/skills/cs-onboard/reference/spec-governance-tools.md rename to plugins/codestable/skills/cs-onboard/references/spec-governance-tools.md diff --git a/plugins/codestable/skills/cs-onboard/references/system-overview.md b/plugins/codestable/skills/cs-onboard/references/system-overview.md new file mode 100644 index 0000000..e6d727f --- /dev/null +++ b/plugins/codestable/skills/cs-onboard/references/system-overview.md @@ -0,0 +1,84 @@ +# CodeStable 体系总览 + +本文档介绍 CodeStable 工作流家族整体：有哪些推荐主入口、各管什么场景、产物怎么组织。 + +CodeStable 把常见开发活动各配一套流程，产物放进统一的 `.codestable/` 目录结构，带统一命名和状态，方便人和 AI 在后续会话里检索复用。 + +## 技能分成四部分 + +**根入口** + +- `cs` — 轻量分诊到推荐主入口；不写 spec、不改产物。 + +**做事主入口** + +- `cs-feat` — 新功能端到端：design → design-review → implementation → code-review → QA → acceptance。想法模糊时先走 `cs-brainstorm`。 +- `cs-issue` — 修 bug 端到端：report → analyze → fix → code-review。 +- `cs-refactor` — 行为不变的结构/性能/可读性优化：标准模式或 fastforward mode。 +- `cs-epic` — 大需求端到端：规划、规划审查、子 feature design、goal 执行包。用户叫 epic；内部第一版仍用 roadmap 目录/doc_type。 +- `cs-goal` — 限定起点/终点后自主迭代实现、验证，完成前做 Task agent 功能验收。 +- `cs-code-review` — 各执行流末端、commit 前的横切独立 diff 评审。 + +**沉淀** + +- `cs-keep` — 把坑点、技巧、决策、调研沉淀到 `.codestable/compound/`。 +- `cs-note` — 把一两行启动必读项目注意事项追加到 `.codestable/attention.md`。 + +**讨论与辅助** + +- `cs-brainstorm` — 想法模糊时分诊到 feature、epic 或 brainstorm note。 +- `cs-onboard` — 把新仓库接入 CodeStable 目录结构。 +- `cs-req` — 起草或刷新 `.codestable/requirements/` 下的需求文档。 +- `cs-domain` — 维护 CONTEXT.md 术语、ADR 决策和单/多 context 拓扑。 +- `cs-audit` — 主动扫描 bug、安全、性能、可维护性和架构偏离。 +- `cs-docs` — 写给外部读者的开发者指南、用户指南或 API 参考。 +- `cs-docs-neat` — 阶段/里程碑收尾时整理 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆。 + +旧阶段技能仍长期可用，但只是兼容入口；共享文档只写主入口和阶段，不把旧入口作为推荐路径。 + +## 场景路由 + +仓库还没有 `.codestable/` 目录时，先用 `cs-onboard` 搭骨架。 + +| 场景 | 主入口 | +|---|---| +| 想法还模糊 / 先聊聊 | `cs-brainstorm` | +| 新功能 / 新能力 | `cs-feat` | +| 限定起点/终点的目标达成 | `cs-goal` | +| BUG / 异常 / 文档错误 | `cs-issue` | +| 代码优化 / 重构 / 重写，且行为不变 | `cs-refactor` | +| 大需求拆解 / 系统级能力 / 执行整个 roadmap | `cs-epic` | +| 合并前代码评审 / 准备 PR | `cs-code-review` | +| 摸代码、踩坑回顾、技术选型、可复用模式 | `cs-keep` | +| 补 / 更新需求文档 | `cs-req` | +| 拍板技术决策 / 加术语 / 分 context | `cs-domain` | +| 开发者指南 / 用户指南 / API 参考 | `cs-docs` | +| 阶段收尾 / 同步 agent 入口 / 新人交接 | `cs-docs-neat` | + +## 档案分层 + +- **愿景档案**（requirements）：用户需要什么、系统提供什么能力。 +- **领域档案**（CONTEXT.md / adrs）：项目术语和结构性决策。 +- **规划档案**（roadmap）：`cs-epic` 的内部存储模型，描述大需求分步实现。 +- **单次动作**（feature / issue / refactor）：本次要做的一件具体事情的 spec 和验证记录。 + +用户说“我想要一个 X 系统”这种大需求，走 `cs-epic` 拆成若干子 feature，再逐条走 `cs-feat`。直接起 feature 容易变成巨型 design。 + +## 阶段不可跳 + +主入口会自动判断阶段，但不会跳过 gate： + +- feature：design → design-review → implementation → code-review → QA → acceptance。 +- issue：report → analyze → fix → code-review；简单问题可走快速通道但仍写 fix-note。 +- refactor：标准模式必须 scan → design → apply → code-review；fastforward 必须行为不变、范围小、可自证。 +- epic：planning → review → 用户确认 → 子 feature design/review → 用户确认 → goal 包。 + +每个 checkpoint 的详细规则在对应主入口及其 `references/` 中。 + +## 进一步参考 + +- `.codestable/reference/shared-conventions.md` — 目录结构、frontmatter 口径、checklist 生命周期和收尾约定。 +- `.codestable/reference/tools.md` — `search-yaml.py` / `validate-yaml.py` 用法。 +- `.codestable/reference/maintainer-notes.md` — 断点恢复和新增子工作流登记。 + +目录结构权威定义在 `shared-conventions.md`。要改目录先改 `plugins/codestable/skills/cs-onboard/references/shared-conventions.md` 模板，新项目 onboard 时会带上新版本。 diff --git a/plugins/codestable/skills/cs-onboard/reference/tools-context.md b/plugins/codestable/skills/cs-onboard/references/tools-context.md similarity index 100% rename from plugins/codestable/skills/cs-onboard/reference/tools-context.md rename to plugins/codestable/skills/cs-onboard/references/tools-context.md diff --git a/plugins/codestable/skills/cs-onboard/reference/tools.md b/plugins/codestable/skills/cs-onboard/references/tools.md similarity index 98% rename from plugins/codestable/skills/cs-onboard/reference/tools.md rename to plugins/codestable/skills/cs-onboard/references/tools.md index befd9d0..023a9bd 100644 --- a/plugins/codestable/skills/cs-onboard/reference/tools.md +++ b/plugins/codestable/skills/cs-onboard/references/tools.md @@ -106,7 +106,7 @@ CODESTABLE_ALLOW_SELF_REVIEW_FALLBACK=1 python3 .codestable/tools/validate-imple ## 4. Roadmap Goal Gates -`cs-onboard` 会把技能包里的 `gates/` 和 gate 脚本释放到项目 `.codestable/`，并清理 `__pycache__` / `*.pyc`。这些 gate 不是全局 PreToolUse 拦截器，而是由 `cs-roadmap-impl-goal` / `cs-feat-*` 在阶段边界显式调用。 +`cs-onboard` 会把技能包里的 `gates/` 和 gate 脚本释放到项目 `.codestable/`，并清理 `__pycache__` / `*.pyc`。这些 gate 不是全局 PreToolUse 拦截器，而是由 `cs-epic` / `cs-feat` 等主入口在阶段边界显式调用。 ```bash python3 .codestable/tools/validate-yaml.py --file .codestable/gates/roadmap-goal-gates.yaml --yaml-only diff --git a/plugins/codestable/skills/cs-onboard/tools/codestable_common.py b/plugins/codestable/skills/cs-onboard/tools/codestable_common.py index 0137c70..7798ac5 100644 --- a/plugins/codestable/skills/cs-onboard/tools/codestable_common.py +++ b/plugins/codestable/skills/cs-onboard/tools/codestable_common.py @@ -66,8 +66,10 @@ KNOWN_SKILL_DIRS = { "cs-code-review", "cs-doc-api", "cs-doc-tutorial", + "cs-docs", "cs-docs-neat", "cs-domain", + "cs-epic", "cs-feat", "cs-feat-accept", "cs-feat-design", diff --git a/plugins/codestable/skills/cs-refactor-ff/SKILL.md b/plugins/codestable/skills/cs-refactor-ff/SKILL.md index c4d5a11..90aaa44 100644 --- a/plugins/codestable/skills/cs-refactor-ff/SKILL.md +++ b/plugins/codestable/skills/cs-refactor-ff/SKILL.md @@ -1,135 +1,23 @@ --- name: cs-refactor-ff -description: 快速重构通道。触发：小重构/简单优化局部函数组件，且可测试自证。 +description: Refactor fastforward 兼容入口。旧调用保留；执行时转入 cs-refactor 主流程的 fastforward 模式。 --- # cs-refactor-ff -## 启动必读 +本技能是 `cs-refactor` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_mode: fastforward` -用户说"优化一下这个函数"而改动明显很小（单函数变长、组件里抽个 composable、一段重复代码合并）时走完整三阶段太重。fastforward 让 AI 像平时一样直接改但守住底线——行为等价、引用经典方法、跑测试自证。 +## 执行规则 -很轻：没有 scan 清单、没有 design doc、没有 checklist，改完一句话汇报就行。 +1. 按已安装 skill 名称加载 `cs-refactor` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-refactor` 主协议继续执行，并带上入口意图 `requested_mode: fastforward`。 +3. 不要要求用户重新调用 `cs-refactor`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -## 执行 gate（worktree + commit） +## 维护规则 -改前运行 start gate，`{slug}` 为 refactor 目录名： - -```bash -python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/refactors/YYYY-MM-DD-{slug} -``` - -gate 不通过不动代码；override 先在 unit 目录写 `worktree-override.md`（reason / scope / approval）。自证通过、提交前运行 commit gate（同命令 `commit`）；不通过先处理 findings。gate 安装与 branch-guard hook 见 `.codestable/reference/branch-guard-hooks.md`。 - ---- - -## 入场 3 条硬检查（不过就退完整流程） - -先做 `shared-conventions.md` 第 7 节的**第一性原则 pre-pass**：外部行为必须不变，不可破约束是公开接口和现有测试，最小充分改动必须能对应到经典重构方法；无法从这些推出的"顺手优化"都不做。 - -任一不过就退到 `cs-refactor`： - -1. **行为真的不变吗？** 用户描述夹带"顺便支持 X / 改成 Y"——这是行为改动不是 refactor，让用户拆出去走 feature / issue -2. **范围真的小吗？** 超过 1 个文件 / 单文件超过 100 行改动 / 预计改动点超过 3 处——退完整流程 -3. **有测试能自证吗？** 目标代码有覆盖（单测 / 集成测 / 类型检查能抓到）——没测试就退完整流程，或先做一个 characterization test 再回来 - -完整 scan 阶段是 7 条入场检查，这里压成最关键 3 条——剩下 4 条（跨模块 / 全口味 / 生成代码 / 扫不完）在"范围真的小吗"里已被隐含排除。 - ---- - -## 用经典方法不发挥 - -fastforward 不读完整方法库，但要守住"**每一处改动都能对应到一个经典重构方法**"。AI 心里想不出"我这步是 Extract Function / Memoization / Guard Clauses / ..." 里的哪一个 → 这次不是简单重构退完整流程查方法库。 - -常用方法（覆盖 fastforward 80% 场景）： - -- **Extract Function**：> 5 行、内聚、能命名的片段 → 抽出独立函数 -- **Extract Variable**：复杂表达式 → 命名变量或 query -- **Guard Clauses**：开头多层嵌套 if 检查 → 提前 return 拉平 -- **Decompose Conditional**：复杂 if 条件 → 命名为布尔函数 -- **Extract Composable / hook**：组件里封闭的状态 + 副作用 → 独立 composable / hook -- **Memoization**：重复计算 → computed / useMemo -- **Cancellation**：副作用缺 cleanup → 加 onUnmounted / useEffect return - -想做的动作不在这几种里、不是开箱即用的经典方法（涉及 Parallel Change / Strangler Fig / 分层纠偏）→ 退完整流程。 - ---- - -## 流程 - -### 1. 一次对齐 - -一句话回用户：**"我打算做 {方法名}，动 {具体文件/函数}，改动点 {N} 处，预计影响 {范围}。确认就开干。"** - -确认就下一步。用户说"还有个 X 要改"——评估 X 是否破坏入场 3 条，破坏了就退完整流程。 - -### 2. 改 - -按经典方法步骤改。不产出 design doc / checklist，代码直接落盘。 - -### 3. 自证 - -- 完成后先进入 `cs-code-review` 做独立 diff 评审；Critical/Important 未清零不进 commit，scoped-commit 发起权归 `cs-code-review` -- 跑测试（单元 / 集成 / 类型检查 / lint） -- grep 检查旧引用是否清理干净（做了 Extract / Inline 这类） -- 改了前端状态逻辑跑类型检查 + 已有测试；**不做 UI 目视验证**——要 UI 目视就不该走 fastforward - -### 4. 一句话汇报 - -``` -✓ 已完成。方法：{方法名}。改动：{文件路径:行号范围}。验证：{跑了什么测试 / 通过情况}。 -``` - -有偏离 / apply 过程中发现想再改点别的 → **停下问用户不发挥**。 - ---- - -## 文件产出 - -默认**不建 `.codestable/refactors/` 目录**——fastforward 的价值就在不留存档。 - -例外：用户明确"这次要留个记录" → 建 `.codestable/refactors/{YYYY-MM-DD}-{slug}/{slug}-refactor-note.md`，内容就是上面那句汇报 + 一段"做了什么 / 为什么"。不写 design / checklist。 - ---- - -## 什么时候跳出 fastforward - -改到一半出现以下任一，**停下告诉用户"比预期复杂，建议切回完整流程"**： - -- 改动点从 3 个涨到 5+ -- 发现要动的文件不止 1 个 -- 冒出一个不在常用方法清单里的动作 -- 发现没有测试能覆盖 -- 用户追加"顺便改一下 X"带入行为改动 -- 改完 AI 自证失败且不是简单修正能搞定 - -切回：触发 `cs-refactor` 从 scan 开始。已改的部分要么提交保留、要么 `git restore` 回到干净状态再扫。 - ---- - -## 不做什么 - -- **不写 scan / design / checklist** —— 写了就违背 fastforward 存在的理由 -- **不跨多文件改** —— 跨文件就不是"小重构" -- **不做需要 HUMAN 目视的改动** —— 前端渲染 / 交互 / 性能感知要人看的走完整流程 -- **不碰公开接口** —— 改公开接口要走 Parallel Change，不是 fastforward 能做的 - ---- - -## 容易踩的坑 - -- **把"小"判断得太宽**：用户说"小重构"但实际动 3 个文件——AI 要老实说"这不算小" -- **跳过入场 3 条检查就开干**：这个技能的意义就在这 3 条 -- **自证偷懒**：只跑类型检查不跑单元测试，或完全不 grep 旧引用 -- **改中发挥**：看到邻居代码也"顺手改改"——fastforward 范围在确认那一刻就锁死 -- **行为改动伪装成重构**：加新参数、改返回值格式——这是行为改动伪装不了 - ---- - -## 相关 - -- `cs-refactor/SKILL.md` — 完整 refactor 流程 -- `cs-refactor/reference/methods.md` — 完整方法库 -- `.codestable/reference/system-overview.md` — CodeStable 体系总览 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-refactor` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-refactor/SKILL.md b/plugins/codestable/skills/cs-refactor/SKILL.md index c7d4e1f..a41b1a4 100644 --- a/plugins/codestable/skills/cs-refactor/SKILL.md +++ b/plugins/codestable/skills/cs-refactor/SKILL.md @@ -1,6 +1,7 @@ --- name: cs-refactor -description: 受控重构入口。触发：优化/重构/拆分/性能/代码太长，且不改变行为、不新增需求。 +description: Refactor 主入口。触发：优化/重构/拆分/性能/代码太长，且不改变行为、不新增需求。 +argument-hint: "[standard|ff|scan|design|apply] [重构目标]" --- # cs-refactor @@ -9,242 +10,87 @@ description: 受控重构入口。触发：优化/重构/拆分/性能/代码太 开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 -AI 自己重构有两个稳定失败模式：一是不知道模块真实需求和约束，改出来的东西功能不等价；二是一次吞掉的范围超过上下文承载，改到后面忘了前面的约束。这流程在"想优化"和"动手改"之间塞了扫描清单 + 方法库，让 AI 只接自己能稳定做对的活。 +`cs-refactor` 是重构的唯一推荐入口。它统一判定标准模式和 fastforward 模式，核心底线是行为等价：一旦会改变外部可观察行为，就转 `cs-feat` 或 `cs-issue`。 -``` -scan（扫优化点清单）→ design（和用户定做哪几条 + 顺序）→ apply（逐条执行，每步人工放行） -``` - -**核心纪律**：行为等价是底线。一旦会改外部可观察行为 → 不走 refactor，走 feature（需求变）或 issue（bug 修）。 - -**架构 deepening 模式**：用户说"架构优化 / 模块太浅 / seam 不对 / 可测试性差 / AI 难导航"时，仍走本技能三阶段，不生成 HTML。scan 用 `codebase-design` 词汇找 deepening opportunities；这是内嵌词汇引用，不切换到独立 `codebase-design` skill。候选项写进标准 `{slug}-scan.md`，用户勾选后再进 design/checklist/apply。 - -## 执行 gate（worktree + commit） - -进入 apply 前运行 start gate，`{slug}` 为 refactor 目录名： - -```bash -python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/refactors/YYYY-MM-DD-{slug} -``` - -gate 不通过不开始改代码；override 时先在 unit 目录写 `worktree-override.md`（reason / scope / approval）。apply 完成、收尾 commit 前运行 commit gate（同命令 `commit`）；不通过先处理 findings。gate 安装与 branch-guard hook 见 `.codestable/reference/branch-guard-hooks.md`。 +`cs-refactor-ff` 长期保留为兼容入口，只传入 `requested_mode: fastforward`。 --- -## Fastforward 模式（小重构） +## 入口意图 -单函数 / 单组件 / 1-3 处优化 / 有测试可自证 / 不需要目视——走完整三阶段太重。触发 `cs-refactor-ff`：直接识别、一次对齐、原地改、跑测试自证，不产 scan / design / checklist。 +本次调用参数：$ARGUMENTS -触发："小重构"、"快速重构"、"简单优化下 XX 函数"、"直接改"、"别那么多步骤"。 +意图来源按优先级：调用参数 > 兼容入口预设 > 用户话术。参数为空或未被替换（仍是字面 `$ARGUMENTS`）时跳过该来源；首个 token 命中下表则设为入口意图，其余文本作为重构目标。 -**别走** ff：改动跨 > 1 文件 / 预计动点 > 3 处 / 需要目视验证 / 改公开接口（要 Parallel Change）/ 没有测试覆盖 / 跨模块。遇到劝用户走标准流程。ff 开干后发现变复杂切回完整流程从 scan 开始。 +| token | 入口意图 | +|---|---| +| `standard` | `requested_mode: standard` | +| `ff` | `requested_mode: fastforward` | +| `scan` | `requested_stage: scan` | +| `design` | `requested_stage: design` | +| `apply` | `requested_stage: apply` | + +入口意图只是偏好。仓库事实优先：已有 scan/design/checklist/apply-notes 时按真实状态续跑。 --- ## 文件放哪儿 -``` +```text .codestable/refactors/{YYYY-MM-DD}-{slug}/ -├── {slug}-scan.md ← 阶段 1 优化点清单 -├── {slug}-refactor-design.md ← 阶段 2 执行方案 -├── {slug}-checklist.yaml ← 阶段 2 生成，阶段 3 推进 -└── {slug}-apply-notes.md ← 阶段 3 执行记录 +├── {slug}-scan.md +├── {slug}-refactor-design.md +├── {slug}-checklist.yaml +└── {slug}-apply-notes.md ``` -目录命名同 feature / issue。slug 短到一眼看出改的是什么（`user-form-split`、`export-perf`）。 - -为什么单独开目录不混进 features：refactor 产物是"代码当前状态扫描 + 执行记录"时效性强；feature 产物是"为什么这样设计"时效性弱。归档逻辑不一样。 +fastforward 默认不建目录；用户要求留记录时才写 `{slug}-refactor-note.md`。 --- -## 三个阶段 +## 模式选择 -| 阶段 | 产出 | 谁主导 | -|---|---|---| -| 1 scan | scan.md | AI 扫 + 前置检查，用户勾选 | -| 2 design | refactor-design.md + checklist.yaml | AI 起草，用户整体 review | -| 3 apply | 代码改动 + apply-notes.md | AI 执行，每步人工放行 | +启动后先确认用户诉求是否真是行为不变的重构，再检查范围和测试自证能力。 -阶段间有 checkpoint：scan 不勾选不进 design；design 不放行不动代码；apply 里 HUMAN 验证项不点头不推进下一步。 +标准模式读取 `references/standard/protocol.md`，流程是： ---- - -## 阶段 1：scan - -### 先跑前置检查（7 条），命中就停 - -动笔扫之前先跑一遍。命中任何一条 → **中止 scan，给路由建议**，不要硬凑。7 条检查和输出格式见 `reference/refusal-routing.md`。 - -零条合法输出——扫完真的没发现值得做的就老实说不要凑。 - -### 扫描范围锁定 - -进 scan 前确认：**这次扫哪些文件**。默认： - -- 用户点名了具体文件 / 组件 → 就扫那些 -- "这个页面" → 入口组件 + 直接 import 的内部模块，不追公共依赖 -- "这个模块" → 模块目录下的文件，不追出模块边界 -- 范围 > 15 文件或 > 3000 行 → 触发第 6 条前置检查请用户先缩范围 - -范围里要包含测试文件（用来判断第 2 条前置检查的测试覆盖）。 - -### 扫的时候看什么 - -按方法库四层当模板找： - -- **L1 行为等价迁移**：函数被很多处调用但接口/实现要改 → Parallel Change；整块老逻辑要被新实现替换 → Strangler Fig -- **L2 代码级重构**：超长函数（> 50 行 / 圈复杂度 > 10）、重复条件片段、神秘临时变量、多层嵌套 if-else -- **L3 结构拆分**：组件 > 300 行 / 文件承担多件事 / 容器与展示混在一起 / 相同逻辑多组件各写一份（前端）；Controller 直接调 DB / Service 缺失 / Repository 被绕开（后端） -- **L4 性能**：重复计算（可 memo）/ N+1 查询 / 列表无虚拟化或分页 / 事件监听无清理 / 大对象深响应（Vue） -- **Architecture deepening**：shallow module、pass-through wrapper、seam 泄漏、假 adapter、测试越过 interface、locality 缺失。候选项分类写"架构"，字段按 `reference/scan-checklist-format.md` 的架构扩展。 - -完整方法库在 `reference/methods.md`、`reference/methods-l4.md` 和 `reference/methods-architecture.md`，扫描时全量加载作匹配表。 - -### 产出格式 - -`{slug}-scan.md` 两部分： - -1. **顶部总览**（一段）：扫描范围 / 发现条数 / 按分类分布 / 按风险分布 / 建议先做哪几条 / 慎做哪几条 -2. **清单条目**（一条一块）：字段顺序和硬约束见 `reference/scan-checklist-format.md` - -整份交给用户，**用户勾选 ✓ / ✗**（✗ 写理由）后进阶段 2。**不要替用户勾选**。 - ---- - -## 阶段 2：design - -### 输入 - -- 用户勾选过的 `{slug}-scan.md` -- 方法库（每条勾选项必须映射到方法号 M-Ln-NN，含 architecture deepening 方法） - -### 做的事 - -1. **排顺序**——勾选条目有依赖的排前（L1 的 Parallel Change 通常先跑，L2 的提取跟在后面）。独立的按"低风险 + AI 可自证"优先，HUMAN 验证项排后批量处理 -2. **每条补执行细节**：方法号 / 步骤 / 前置条件 / 退出信号 / 验证责任方（AI / HUMAN）/ 回滚策略 -3. **识别前置依赖**——测试覆盖不够的条目前置"补刻画测试"；改公开接口的前置"搜调用方" -4. **整体 review**：整稿交用户，放行后 `status: approved` -5. **抽 checklist**：steps 对应执行顺序，checks 对应每步退出信号 - -### design 文件结构 - -```markdown ---- -doc_type: refactor-design -refactor: {YYYY-MM-DD}-{slug} -status: draft | approved -scope: {扫描范围一句话} -summary: {本次要做的几条是什么，一句话} ---- - -# {slug} refactor design - -## 1. 本次范围 -- 从 scan 勾选了哪几条（编号） -- 明确不做的（被 ✗ 的）和理由 -- 预估总工作量 / 总风险档位 - -## 2. 前置依赖 -- 测试覆盖补齐（如需） -- 调用方搜索（如需） -- 其他一次性准备 - -## 3. 执行顺序 -按步骤列，每步一块： -- 步骤 N：{一句话动作} -- 引用方法：M-Ln-NN {方法名} -- 具体操作：{照方法库步骤落到本项目具体文件 / 函数} -- 退出信号：{AI 跑什么测试 / HUMAN 看什么页面} -- 验证责任：AI 自证 ｜ HUMAN -- 回滚：{出问题怎么还原，通常 git revert 某步} - -## 4. 风险与看点 -- 高风险步骤汇总 -- 容易出错的点（跨步骤数据流变化等） +```text +scan → 用户勾选 → design → 用户确认 → apply → cs-code-review ``` +fastforward 模式读取 `references/fastforward/protocol.md`。必须同时满足： + +1. 行为真的不变，没有“顺便支持 X / 改成 Y”。 +2. 范围小：单函数/单组件/少量动点，不跨模块。 +3. 有测试、类型检查或等价证据能自证。 + +任何一条不满足，回标准模式；不能因为用户说“快点”就跳过安全边界。 + --- -## 阶段 3：apply +## Reference 加载 -### 推进规则 +- standard：`references/standard/protocol.md` +- fastforward：`references/fastforward/protocol.md` +- 方法库：`references/library/methods.md`、`references/library/methods-l4.md`、`references/library/methods-architecture.md` +- scan 格式与拒绝路由：`references/library/scan-checklist-format.md`、`references/library/refusal-routing.md` +- code review：公开横切技能 `cs-code-review` -1. **一步一做不批量**——严格按 checklist 顺序，当前步不完成不开下一步 -2. **每步完成走验证**： - - AI 自证：跑指定测试 / 类型检查 / lint / grep 无残留旧引用。通过了记 apply-notes 继续 - - HUMAN 验证：**停下来**汇报"第 N 步已完成，请在 {具体页面 / 操作} 目视确认，确认后我继续"。用户不明确说"继续"就不推进 -3. **偏离当场记**——执行中发现方案没考虑的情况（如有个调用方在动态 import 里），**停下来汇报不发挥**。和用户对齐后追加到 apply-notes，必要时回阶段 2 改 design -4. **行为等价自检**——每步结束额外问"这一步有没有可能改了外部可观察行为？" 有怀疑就退回当步 +按阶段加载，scan 时才全量加载方法库。 -### apply-notes 格式 - -```markdown ---- -doc_type: refactor-apply-notes -refactor: {YYYY-MM-DD}-{slug} --- -# {slug} apply notes +## 人工 checkpoint -## 步骤 1: {动作} -- 完成时间: {date} -- 改动文件: {file list} -- 验证结果: {测试输出 / HUMAN 确认语录} -- 偏离: {无 / 具体描述} - -## 步骤 2: ... -``` - -### 全部完成后 - -- 完成后先进入 `cs-code-review` 做独立 diff 评审；Critical/Important 未清零不进 commit，scoped-commit 发起权归 `cs-code-review` -- 跑全量测试 + 类型检查 + lint -- 最后一次请用户整体目视确认（前端：打开主要页面点一圈） -- 确认通过后收尾 commit，message 引用 refactor 目录 +- scan 产物必须由用户勾选，AI 不替用户勾选。 +- design 必须用户整体 review 后才进入 apply。 +- apply 中 HUMAN 验证项必须停下等用户明确继续。 +- 完成后进入 `cs-code-review`；Critical/Important 未清零不提交。 --- ## 退出条件 -- [ ] scan 前置检查跑过，命中的已路由，没命中的才进 scan -- [ ] `{slug}-scan.md` 用户已勾选（✓/✗） -- [ ] design 每条勾选项映射到方法号 -- [ ] design 用户整体 review 通过 `status: approved` -- [ ] checklist.yaml 已生成且通过 `validate-yaml.py` -- [ ] apply 每步都有验证记录（AI 自证贴日志，HUMAN 贴用户确认语录） -- [ ] 全量测试 / 类型检查 / lint 通过 -- [ ] 用户最后一次目视确认通过 - ---- - -## 容易踩的坑 - -- **AI 硬凑清单**——前置检查明显命中却找理由绕过，扫出一堆"代码可以更优雅"无量化问题的条目 -- **夹带行为改动**——在重构中间"顺便修了 bug / 优化提示文案"——拆成独立 issue 或 feature -- **跨步骤合并动作**——一次提交做 2-3 步，失去"单步回滚"能力 -- **把口味项列进清单**——命名偏好 / 引号 / 箭头函数 vs function——走 decisions -- **扫大模块直接动手**——> 15 文件 / > 3000 行不拆就进 scan，产出没法决策的长清单 -- **HUMAN 验证项自己跳过**——前端效果 AI 看不到，不能用"类型检查过了"替代人工目视 -- **覆盖率不够硬上**——没测试的模块直接改，"行为等价"只是口头承诺 - ---- - -## 与相邻工作流的边界 - -- **feature**：加新能力 / 改需求。refactor 里冒出"顺便实现 X"停下拆出去 -- **issue**：修 bug / 行为错了。refactor 里发现的 bug 记成新 issue 不偷偷修 -- **decisions**：全项目长期约束（"以后都用 composable"、"禁用 mixin"）。refactor 可引用已有 decision 但不产出 decision -- **architecture**：跨模块边界重划 / 分层调整。单次 refactor 不跨模块；跨模块要拆成"更新架构 + 记决策 + N 个模块级 refactor" -- **tricks / learning**：refactor 中发现的手法 → tricks；踩的坑 → learning - ---- - -## 相关文档 - -- `cs-refactor-ff/SKILL.md` — 小重构超轻量通道 -- `reference/scan-checklist-format.md` — scan 清单条目字段 / 顺序 / 硬约束 -- `reference/refusal-routing.md` — scan 前置检查 7 条 + 路由表 -- `reference/methods.md` — 方法库（L1-L3） -- `reference/methods-l4.md` — 方法库（L4 性能与异步） -- `reference/methods-architecture.md` — 方法库（architecture deepening） -- `.codestable/reference/shared-conventions.md` — 跨工作流共享口径 +- 标准模式：scan 已勾选、design approved、apply-notes 记录每步验证、必要测试通过、code review 通过。 +- fastforward：已说明方法、范围、验证证据；如变复杂已停下切回标准模式。 +- 不夹带 feature 或 issue 改动。 diff --git a/plugins/codestable/skills/cs-refactor/references/fastforward/protocol.md b/plugins/codestable/skills/cs-refactor/references/fastforward/protocol.md new file mode 100644 index 0000000..a976e02 --- /dev/null +++ b/plugins/codestable/skills/cs-refactor/references/fastforward/protocol.md @@ -0,0 +1,126 @@ +# Refactor Fastforward Protocol + +用户说"优化一下这个函数"而改动明显很小（单函数变长、组件里抽个 composable、一段重复代码合并）时走完整三阶段太重。fastforward 让 AI 像平时一样直接改但守住底线——行为等价、引用经典方法、跑测试自证。 + +很轻：没有 scan 清单、没有 design doc、没有 checklist，改完一句话汇报就行。 + +## 执行 gate（worktree + commit） + +改前运行 start gate，`{slug}` 为 refactor 目录名： + +```bash +python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/refactors/YYYY-MM-DD-{slug} +``` + +gate 不通过不动代码；override 先在 unit 目录写 `worktree-override.md`（reason / scope / approval）。自证通过、提交前运行 commit gate（同命令 `commit`）；不通过先处理 findings。gate 安装与 branch-guard hook 见 `.codestable/reference/branch-guard-hooks.md`。 + +--- + +## 入场 3 条硬检查（不过就退完整流程） + +先做 `shared-conventions.md` 第 7 节的**第一性原则 pre-pass**：外部行为必须不变，不可破约束是公开接口和现有测试，最小充分改动必须能对应到经典重构方法；无法从这些推出的"顺手优化"都不做。 + +任一不过就退到 `cs-refactor`： + +1. **行为真的不变吗？** 用户描述夹带"顺便支持 X / 改成 Y"——这是行为改动不是 refactor，让用户拆出去走 feature / issue +2. **范围真的小吗？** 超过 1 个文件 / 单文件超过 100 行改动 / 预计改动点超过 3 处——退完整流程 +3. **有测试能自证吗？** 目标代码有覆盖（单测 / 集成测 / 类型检查能抓到）——没测试就退完整流程，或先做一个 characterization test 再回来 + +完整 scan 阶段是 7 条入场检查，这里压成最关键 3 条——剩下 4 条（跨模块 / 全口味 / 生成代码 / 扫不完）在"范围真的小吗"里已被隐含排除。 + +--- + +## 用经典方法不发挥 + +fastforward 不读完整方法库，但要守住"**每一处改动都能对应到一个经典重构方法**"。AI 心里想不出"我这步是 Extract Function / Memoization / Guard Clauses / ..." 里的哪一个 → 这次不是简单重构退完整流程查方法库。 + +常用方法（覆盖 fastforward 80% 场景）： + +- **Extract Function**：> 5 行、内聚、能命名的片段 → 抽出独立函数 +- **Extract Variable**：复杂表达式 → 命名变量或 query +- **Guard Clauses**：开头多层嵌套 if 检查 → 提前 return 拉平 +- **Decompose Conditional**：复杂 if 条件 → 命名为布尔函数 +- **Extract Composable / hook**：组件里封闭的状态 + 副作用 → 独立 composable / hook +- **Memoization**：重复计算 → computed / useMemo +- **Cancellation**：副作用缺 cleanup → 加 onUnmounted / useEffect return + +想做的动作不在这几种里、不是开箱即用的经典方法（涉及 Parallel Change / Strangler Fig / 分层纠偏）→ 退完整流程。 + +--- + +## 流程 + +### 1. 一次对齐 + +一句话回用户：**"我打算做 {方法名}，动 {具体文件/函数}，改动点 {N} 处，预计影响 {范围}。确认就开干。"** + +确认就下一步。用户说"还有个 X 要改"——评估 X 是否破坏入场 3 条，破坏了就退完整流程。 + +### 2. 改 + +按经典方法步骤改。不产出 design doc / checklist，代码直接落盘。 + +### 3. 自证 + +- 完成后先进入 `cs-code-review` 做独立 diff 评审；Critical/Important 未清零不进 commit，scoped-commit 发起权归 `cs-code-review` +- 跑测试（单元 / 集成 / 类型检查 / lint） +- grep 检查旧引用是否清理干净（做了 Extract / Inline 这类） +- 改了前端状态逻辑跑类型检查 + 已有测试；**不做 UI 目视验证**——要 UI 目视就不该走 fastforward + +### 4. 一句话汇报 + +``` +✓ 已完成。方法：{方法名}。改动：{文件路径:行号范围}。验证：{跑了什么测试 / 通过情况}。 +``` + +有偏离 / apply 过程中发现想再改点别的 → **停下问用户不发挥**。 + +--- + +## 文件产出 + +默认**不建 `.codestable/refactors/` 目录**——fastforward 的价值就在不留存档。 + +例外：用户明确"这次要留个记录" → 建 `.codestable/refactors/{YYYY-MM-DD}-{slug}/{slug}-refactor-note.md`，内容就是上面那句汇报 + 一段"做了什么 / 为什么"。不写 design / checklist。 + +--- + +## 什么时候跳出 fastforward + +改到一半出现以下任一，**停下告诉用户"比预期复杂，建议切回完整流程"**： + +- 改动点从 3 个涨到 5+ +- 发现要动的文件不止 1 个 +- 冒出一个不在常用方法清单里的动作 +- 发现没有测试能覆盖 +- 用户追加"顺便改一下 X"带入行为改动 +- 改完 AI 自证失败且不是简单修正能搞定 + +切回：进入 `cs-refactor` standard 模式，从 scan 开始。已改的部分要么提交保留、要么 `git restore` 回到干净状态再扫。 + +--- + +## 不做什么 + +- **不写 scan / design / checklist** —— 写了就违背 fastforward 存在的理由 +- **不跨多文件改** —— 跨文件就不是"小重构" +- **不做需要 HUMAN 目视的改动** —— 前端渲染 / 交互 / 性能感知要人看的走完整流程 +- **不碰公开接口** —— 改公开接口要走 Parallel Change，不是 fastforward 能做的 + +--- + +## 容易踩的坑 + +- **把"小"判断得太宽**：用户说"小重构"但实际动 3 个文件——AI 要老实说"这不算小" +- **跳过入场 3 条检查就开干**：这个技能的意义就在这 3 条 +- **自证偷懒**：只跑类型检查不跑单元测试，或完全不 grep 旧引用 +- **改中发挥**：看到邻居代码也"顺手改改"——fastforward 范围在确认那一刻就锁死 +- **行为改动伪装成重构**：加新参数、改返回值格式——这是行为改动伪装不了 + +--- + +## 相关 + +- `cs-refactor` 主入口 — refactor 流程骨架 +- `references/library/methods.md` — 完整方法库 +- `.codestable/reference/system-overview.md` — CodeStable 体系总览 diff --git a/plugins/codestable/skills/cs-refactor/reference/methods-architecture.md b/plugins/codestable/skills/cs-refactor/references/library/methods-architecture.md similarity index 100% rename from plugins/codestable/skills/cs-refactor/reference/methods-architecture.md rename to plugins/codestable/skills/cs-refactor/references/library/methods-architecture.md diff --git a/plugins/codestable/skills/cs-refactor/reference/methods-l4.md b/plugins/codestable/skills/cs-refactor/references/library/methods-l4.md similarity index 100% rename from plugins/codestable/skills/cs-refactor/reference/methods-l4.md rename to plugins/codestable/skills/cs-refactor/references/library/methods-l4.md diff --git a/plugins/codestable/skills/cs-refactor/reference/methods.md b/plugins/codestable/skills/cs-refactor/references/library/methods.md similarity index 100% rename from plugins/codestable/skills/cs-refactor/reference/methods.md rename to plugins/codestable/skills/cs-refactor/references/library/methods.md diff --git a/plugins/codestable/skills/cs-refactor/reference/refusal-routing.md b/plugins/codestable/skills/cs-refactor/references/library/refusal-routing.md similarity index 100% rename from plugins/codestable/skills/cs-refactor/reference/refusal-routing.md rename to plugins/codestable/skills/cs-refactor/references/library/refusal-routing.md diff --git a/plugins/codestable/skills/cs-refactor/reference/scan-checklist-format.md b/plugins/codestable/skills/cs-refactor/references/library/scan-checklist-format.md similarity index 99% rename from plugins/codestable/skills/cs-refactor/reference/scan-checklist-format.md rename to plugins/codestable/skills/cs-refactor/references/library/scan-checklist-format.md index 70aa837..fb369ad 100644 --- a/plugins/codestable/skills/cs-refactor/reference/scan-checklist-format.md +++ b/plugins/codestable/skills/cs-refactor/references/library/scan-checklist-format.md @@ -121,7 +121,7 @@ AI 生成条目必须守，违反要自我纠正重写。 ## 反模式样本 -写进 SKILL.md 的 AI 一眼就能对照检查。 +写入 scan 清单后，执行者能直接对照检查。 ### ❌ 反模式 1：形容词堆砌 diff --git a/plugins/codestable/skills/cs-refactor/references/standard/protocol.md b/plugins/codestable/skills/cs-refactor/references/standard/protocol.md new file mode 100644 index 0000000..2bba9af --- /dev/null +++ b/plugins/codestable/skills/cs-refactor/references/standard/protocol.md @@ -0,0 +1,241 @@ +# Refactor Standard Protocol + +AI 自己重构有两个稳定失败模式：一是不知道模块真实需求和约束，改出来的东西功能不等价；二是一次吞掉的范围超过上下文承载，改到后面忘了前面的约束。这流程在"想优化"和"动手改"之间塞了扫描清单 + 方法库，让 AI 只接自己能稳定做对的活。 + +``` +scan（扫优化点清单）→ design（和用户定做哪几条 + 顺序）→ apply（逐条执行，每步人工放行） +``` + +**核心纪律**：行为等价是底线。一旦会改外部可观察行为 → 不走 refactor，走 feature（需求变）或 issue（bug 修）。 + +**架构 deepening 模式**：用户说"架构优化 / 模块太浅 / seam 不对 / 可测试性差 / AI 难导航"时，仍走本协议三阶段，不生成 HTML。scan 用 `codebase-design` 词汇找 deepening opportunities；这是内嵌词汇引用，不切换到独立 `codebase-design` skill。候选项写进标准 `{slug}-scan.md`，用户勾选后再进 design/checklist/apply。 + +## 执行 gate（worktree + commit） + +进入 apply 前运行 start gate，`{slug}` 为 refactor 目录名： + +```bash +python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/refactors/YYYY-MM-DD-{slug} +``` + +gate 不通过不开始改代码；override 时先在 unit 目录写 `worktree-override.md`（reason / scope / approval）。apply 完成、收尾 commit 前运行 commit gate（同命令 `commit`）；不通过先处理 findings。gate 安装与 branch-guard hook 见 `.codestable/reference/branch-guard-hooks.md`。 + +--- + +## Fastforward 模式（小重构） + +单函数 / 单组件 / 1-3 处优化 / 有测试可自证 / 不需要目视——走完整三阶段太重。进入 `cs-refactor` fastforward 模式：直接识别、一次对齐、原地改、跑测试自证，不产 scan / design / checklist。 + +适用话术："小重构"、"快速重构"、"简单优化下 XX 函数"、"直接改"、"别那么多步骤"。 + +**别走** ff：改动跨 > 1 文件 / 预计动点 > 3 处 / 需要目视验证 / 改公开接口（要 Parallel Change）/ 没有测试覆盖 / 跨模块。遇到劝用户走标准流程。ff 开干后发现变复杂切回完整流程从 scan 开始。 + +--- + +## 文件放哪儿 + +``` +.codestable/refactors/{YYYY-MM-DD}-{slug}/ +├── {slug}-scan.md ← 阶段 1 优化点清单 +├── {slug}-refactor-design.md ← 阶段 2 执行方案 +├── {slug}-checklist.yaml ← 阶段 2 生成，阶段 3 推进 +└── {slug}-apply-notes.md ← 阶段 3 执行记录 +``` + +目录命名同 feature / issue。slug 短到一眼看出改的是什么（`user-form-split`、`export-perf`）。 + +为什么单独开目录不混进 features：refactor 产物是"代码当前状态扫描 + 执行记录"时效性强；feature 产物是"为什么这样设计"时效性弱。归档逻辑不一样。 + +--- + +## 三个阶段 + +| 阶段 | 产出 | 谁主导 | +|---|---|---| +| 1 scan | scan.md | AI 扫 + 前置检查，用户勾选 | +| 2 design | refactor-design.md + checklist.yaml | AI 起草，用户整体 review | +| 3 apply | 代码改动 + apply-notes.md | AI 执行，每步人工放行 | + +阶段间有 checkpoint：scan 不勾选不进 design；design 不放行不动代码；apply 里 HUMAN 验证项不点头不推进下一步。 + +--- + +## 阶段 1：scan + +### 先跑前置检查（7 条），命中就停 + +动笔扫之前先跑一遍。命中任何一条 → **中止 scan，给路由建议**，不要硬凑。7 条检查和输出格式见 `../library/refusal-routing.md`。 + +零条合法输出——扫完真的没发现值得做的就老实说不要凑。 + +### 扫描范围锁定 + +进 scan 前确认：**这次扫哪些文件**。默认： + +- 用户点名了具体文件 / 组件 → 就扫那些 +- "这个页面" → 入口组件 + 直接 import 的内部模块，不追公共依赖 +- "这个模块" → 模块目录下的文件，不追出模块边界 +- 范围 > 15 文件或 > 3000 行 → 触发第 6 条前置检查请用户先缩范围 + +范围里要包含测试文件（用来判断第 2 条前置检查的测试覆盖）。 + +### 扫的时候看什么 + +按方法库四层当模板找： + +- **L1 行为等价迁移**：函数被很多处调用但接口/实现要改 → Parallel Change；整块老逻辑要被新实现替换 → Strangler Fig +- **L2 代码级重构**：超长函数（> 50 行 / 圈复杂度 > 10）、重复条件片段、神秘临时变量、多层嵌套 if-else +- **L3 结构拆分**：组件 > 300 行 / 文件承担多件事 / 容器与展示混在一起 / 相同逻辑多组件各写一份（前端）；Controller 直接调 DB / Service 缺失 / Repository 被绕开（后端） +- **L4 性能**：重复计算（可 memo）/ N+1 查询 / 列表无虚拟化或分页 / 事件监听无清理 / 大对象深响应（Vue） +- **Architecture deepening**：shallow module、pass-through wrapper、seam 泄漏、假 adapter、测试越过 interface、locality 缺失。候选项分类写"架构"，字段按 `../library/scan-checklist-format.md` 的架构扩展。 + +完整方法库在 `../library/methods.md`、`../library/methods-l4.md` 和 `../library/methods-architecture.md`，扫描时全量加载作匹配表。 + +### 产出格式 + +`{slug}-scan.md` 两部分： + +1. **顶部总览**（一段）：扫描范围 / 发现条数 / 按分类分布 / 按风险分布 / 建议先做哪几条 / 慎做哪几条 +2. **清单条目**（一条一块）：字段顺序和硬约束见 `../library/scan-checklist-format.md` + +整份交给用户，**用户勾选 ✓ / ✗**（✗ 写理由）后进阶段 2。**不要替用户勾选**。 + +--- + +## 阶段 2：design + +### 输入 + +- 用户勾选过的 `{slug}-scan.md` +- 方法库（每条勾选项必须映射到方法号 M-Ln-NN，含 architecture deepening 方法） + +### 做的事 + +1. **排顺序**——勾选条目有依赖的排前（L1 的 Parallel Change 通常先跑，L2 的提取跟在后面）。独立的按"低风险 + AI 可自证"优先，HUMAN 验证项排后批量处理 +2. **每条补执行细节**：方法号 / 步骤 / 前置条件 / 退出信号 / 验证责任方（AI / HUMAN）/ 回滚策略 +3. **识别前置依赖**——测试覆盖不够的条目前置"补刻画测试"；改公开接口的前置"搜调用方" +4. **整体 review**：整稿交用户，放行后 `status: approved` +5. **抽 checklist**：steps 对应执行顺序，checks 对应每步退出信号 + +### design 文件结构 + +```markdown +--- +doc_type: refactor-design +refactor: {YYYY-MM-DD}-{slug} +status: draft | approved +scope: {扫描范围一句话} +summary: {本次要做的几条是什么，一句话} +--- + +# {slug} refactor design + +## 1. 本次范围 +- 从 scan 勾选了哪几条（编号） +- 明确不做的（被 ✗ 的）和理由 +- 预估总工作量 / 总风险档位 + +## 2. 前置依赖 +- 测试覆盖补齐（如需） +- 调用方搜索（如需） +- 其他一次性准备 + +## 3. 执行顺序 +按步骤列，每步一块： +- 步骤 N：{一句话动作} +- 引用方法：M-Ln-NN {方法名} +- 具体操作：{照方法库步骤落到本项目具体文件 / 函数} +- 退出信号：{AI 跑什么测试 / HUMAN 看什么页面} +- 验证责任：AI 自证 ｜ HUMAN +- 回滚：{出问题怎么还原，通常 git revert 某步} + +## 4. 风险与看点 +- 高风险步骤汇总 +- 容易出错的点（跨步骤数据流变化等） +``` + +--- + +## 阶段 3：apply + +### 推进规则 + +1. **一步一做不批量**——严格按 checklist 顺序，当前步不完成不开下一步 +2. **每步完成走验证**： + - AI 自证：跑指定测试 / 类型检查 / lint / grep 无残留旧引用。通过了记 apply-notes 继续 + - HUMAN 验证：**停下来**汇报"第 N 步已完成，请在 {具体页面 / 操作} 目视确认，确认后我继续"。用户不明确说"继续"就不推进 +3. **偏离当场记**——执行中发现方案没考虑的情况（如有个调用方在动态 import 里），**停下来汇报不发挥**。和用户对齐后追加到 apply-notes，必要时回阶段 2 改 design +4. **行为等价自检**——每步结束额外问"这一步有没有可能改了外部可观察行为？" 有怀疑就退回当步 + +### apply-notes 格式 + +```markdown +--- +doc_type: refactor-apply-notes +refactor: {YYYY-MM-DD}-{slug} +--- + +# {slug} apply notes + +## 步骤 1: {动作} +- 完成时间: {date} +- 改动文件: {file list} +- 验证结果: {测试输出 / HUMAN 确认语录} +- 偏离: {无 / 具体描述} + +## 步骤 2: ... +``` + +### 全部完成后 + +- 完成后先进入 `cs-code-review` 做独立 diff 评审；Critical/Important 未清零不进 commit，scoped-commit 发起权归 `cs-code-review` +- 跑全量测试 + 类型检查 + lint +- 最后一次请用户整体目视确认（前端：打开主要页面点一圈） +- 确认通过后收尾 commit，message 引用 refactor 目录 + +--- + +## 退出条件 + +- [ ] scan 前置检查跑过，命中的已路由，没命中的才进 scan +- [ ] `{slug}-scan.md` 用户已勾选（✓/✗） +- [ ] design 每条勾选项映射到方法号 +- [ ] design 用户整体 review 通过 `status: approved` +- [ ] checklist.yaml 已生成且通过 `validate-yaml.py` +- [ ] apply 每步都有验证记录（AI 自证贴日志，HUMAN 贴用户确认语录） +- [ ] 全量测试 / 类型检查 / lint 通过 +- [ ] 用户最后一次目视确认通过 + +--- + +## 容易踩的坑 + +- **AI 硬凑清单**——前置检查明显命中却找理由绕过，扫出一堆"代码可以更优雅"无量化问题的条目 +- **夹带行为改动**——在重构中间"顺便修了 bug / 优化提示文案"——拆成独立 issue 或 feature +- **跨步骤合并动作**——一次提交做 2-3 步，失去"单步回滚"能力 +- **把口味项列进清单**——命名偏好 / 引号 / 箭头函数 vs function——走 decisions +- **扫大模块直接动手**——> 15 文件 / > 3000 行不拆就进 scan，产出没法决策的长清单 +- **HUMAN 验证项自己跳过**——前端效果 AI 看不到，不能用"类型检查过了"替代人工目视 +- **覆盖率不够硬上**——没测试的模块直接改，"行为等价"只是口头承诺 + +--- + +## 与相邻工作流的边界 + +- **feature**：加新能力 / 改需求。refactor 里冒出"顺便实现 X"停下拆出去 +- **issue**：修 bug / 行为错了。refactor 里发现的 bug 记成新 issue 不偷偷修 +- **decisions**：全项目长期约束（"以后都用 composable"、"禁用 mixin"）。refactor 可引用已有 decision 但不产出 decision +- **architecture**：跨模块边界重划 / 分层调整。单次 refactor 不跨模块；跨模块要拆成"更新架构 + 记决策 + N 个模块级 refactor" +- **tricks / learning**：refactor 中发现的手法 → tricks；踩的坑 → learning + +--- + +## 相关文档 + +- `../fastforward/protocol.md` — 小重构超轻量通道 +- `../library/scan-checklist-format.md` — scan 清单条目字段 / 顺序 / 硬约束 +- `../library/refusal-routing.md` — scan 前置检查 7 条 + 路由表 +- `../library/methods.md` — 方法库（L1-L3） +- `../library/methods-l4.md` — 方法库（L4 性能与异步） +- `../library/methods-architecture.md` — 方法库（architecture deepening） +- `.codestable/reference/shared-conventions.md` — 跨工作流共享口径 diff --git a/plugins/codestable/skills/cs-req/SKILL.md b/plugins/codestable/skills/cs-req/SKILL.md index c6223d3..ab9290d 100644 --- a/plugins/codestable/skills/cs-req/SKILL.md +++ b/plugins/codestable/skills/cs-req/SKILL.md @@ -23,7 +23,7 @@ description: 能力愿景维护。触发：起草/回填/更新 requirements， **backfill 路径保留**：已经在跑但从没写过 req 的能力，走 backfill 直接落 `status: current`。 -**不记"怎么分步实现"**——那是 `cs-roadmap` 的事。req 只回答"要什么、为什么"，不回答"第几个 sprint 做、拆成几个子 feature"。 +**不记"怎么分步实现"**——那是 `cs-epic` planning 阶段的事（内部仍落 roadmap 文档）。req 只回答"要什么、为什么"，不回答"第几个 sprint 做、拆成几个子 feature"。 需求文档价值在**扫一眼就抓到重点**——用户故事在最前、痛点和解法各一段短的、边界用列表。AI 容易破坏这个特性的几种问题： @@ -45,7 +45,7 @@ description: 能力愿景维护。触发：起草/回填/更新 requirements， - 用户主动修订：能力演进了要刷新（`update`） - 用户主动起草愿景：还没排期的未来需求先落一份 `draft` req 把定位定下来 -不适用：拍板架构决策 / 加术语 → `cs-domain`；写单次 feature 方案 → `cs-feat-design`；操作性沉淀 → `cs-keep`；写外部"怎么用" → `cs-doc-tutorial`；大需求拆几轮做 → `cs-roadmap`。 +不适用：拍板架构决策 / 加术语 → `cs-domain`；写单次 feature 方案 → `cs-feat` design 阶段；操作性沉淀 → `cs-keep`；写外部"怎么用" → `cs-docs` tutorial mode；大需求拆几轮做 → `cs-epic`。 --- @@ -201,9 +201,9 @@ tags: [] |---|---| | `cs-domain` 配合 | req 写"为什么要有"、cs-domain 管 CONTEXT 术语 / 拍板 ADR；ADR frontmatter 可用 `relates_to: [requirements/{req-slug}]` 反向链 | | `cs-brainstorm` 可触发 | 磋商后愿景清晰时可触发 `draft` 模式起草愿景 req | -| `cs-feat-design` 可写 | design 读已有 req 对齐用户故事和边界；新能力首次设计方案化时触发 `draft` 模式起草愿景 req | -| `cs-feat-accept` 主路径 | 验收统一处理 req 落档：draft req 对应的能力实现完成触发 `update`（draft → current，保留愿景追加变更日志）；从未写过 req 的能力触发 `backfill`（直接落 current）；已有 current req 的能力改变触发 `update` 刷新 | -| `cs-roadmap` 配合 | req 记"要什么、为什么"、roadmap 记"怎么分步实现"。roadmap 条目可关联 req slug，但 req 不绑定具体 roadmap。draft req 不给 roadmap 压力——愿景可以先于排期存在 | +| `cs-feat` design 阶段可写 | design 读已有 req 对齐用户故事和边界；新能力首次设计方案化时触发 `draft` 模式起草愿景 req | +| `cs-feat` acceptance 阶段主路径 | 验收统一处理 req 落档：draft req 对应的能力实现完成触发 `update`（draft → current，保留愿景追加变更日志）；从未写过 req 的能力触发 `backfill`（直接落 current）；已有 current req 的能力改变触发 `update` 刷新 | +| `cs-epic` 配合 | req 记"要什么、为什么"、roadmap 记"怎么分步实现"。roadmap 条目可关联 req slug，但 req 不绑定具体 roadmap。draft req 不给 roadmap 压力——愿景可以先于排期存在 | | `cs-onboard` 创建者 | onboard 建 `requirements/` 空目录 + `VISION.md` 空骨架 | --- diff --git a/plugins/codestable/skills/cs-roadmap-impl-goal/SKILL.md b/plugins/codestable/skills/cs-roadmap-impl-goal/SKILL.md index c55907e..92f67a5 100644 --- a/plugins/codestable/skills/cs-roadmap-impl-goal/SKILL.md +++ b/plugins/codestable/skills/cs-roadmap-impl-goal/SKILL.md @@ -1,230 +1,23 @@ --- name: cs-roadmap-impl-goal -description: Roadmap goal 编排。触发：完整推进大需求、执行整个 roadmap、输出 /goal 指令。 +description: Epic goal-package 兼容入口。旧 roadmap goal 调用保留；执行时转入 cs-epic 主流程的 goal-package 阶段。 --- # cs-roadmap-impl-goal -## 启动必读 +本技能是 `cs-epic` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_stage: goal-package` ---- +## 执行规则 -## 目标 +1. 按已安装 skill 名称加载 `cs-epic` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-epic` 主协议继续执行，并带上入口意图 `requested_stage: goal-package`。 +3. 不要要求用户重新调用 `cs-epic`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -把一个大需求变成可审阅、可恢复、可自动推进的 CodeStable roadmap 执行包： +## 维护规则 -1. 先按 `cs-roadmap` 规范澄清需求并创建 / 更新一份 roadmap，运行 `cs-roadmap-review` 并处理到通过。 -2. 用户确认 roadmap 后，为 roadmap items 里的每个子 feature 运行 `cs-feat-design`，生成 design + checklist，运行 `cs-feat-design-review` 并处理到通过。 -3. 用户确认所有 feature design 后，输出一条可直接粘贴的 `/goal` 指令。 -4. `/goal` 会话按顺序循环执行每个 feature：`cs-feat-impl` → `cs-code-review` → 必要时 review-fix → `cs-feat-qa` → 必要时 qa-fix 后重跑 review/QA → `cs-feat-accept` → 更新状态 → 下一个 feature。 -5. 全部 feature 验收后，做整个 roadmap 的最终审计；只有审计通过才打印完成标记。 - -注意：不要把长任务正文塞进 `/goal` 参数。长协议和 feature 执行规格写入 roadmap 自己的目录，`/goal` 只引用这些文件和终止标记。 - ---- - -## 目录约定 - -**复用 `cs-roadmap` 的目录，不创建独立顶层目录。** - -在现有 roadmap 目录下增加 goal 执行文件： - -```text -.codestable/roadmap/{slug}/ -├── {slug}-roadmap.md -├── {slug}-items.yaml -├── {slug}-roadmap-review.md -├── goal-plan.md # 本次 goal 执行总览：假设 / 风险 / feature 顺序 / 验证命令 -├── goal-state.yaml # goal 会话实时状态 -├── goal-protocol.md # 从 references/protocol*.md 复制并按 slug 落地 -├── goal-protocol-feature-loop.md -├── goal-protocol-gates.md -├── goal-protocol-audit.md -├── goal-audit.md # goal 会话结束前生成的最终 roadmap 审计报告 -└── goal-features/ - └── {feature-slug}.md # 每个 feature 的执行规格，指向 design/checklist -``` - -普通 feature 仍放在标准目录： - -```text -.codestable/features/{YYYY-MM-DD}-{feature-slug}/ -├── {feature-slug}-design.md -├── {feature-slug}-checklist.yaml -├── {feature-slug}-design-review.md -├── {feature-slug}-review.md # goal 执行时生成 -├── {feature-slug}-qa.md # goal 执行时生成 -└── {feature-slug}-acceptance.md # goal 执行时生成 -``` - ---- - -## 两次确认门禁 - -本技能必须按两次确认推进，不能跳过。 - -### 第一次确认：roadmap - -先完成 `cs-roadmap` 的 new / update 流程，并通过人审前 review gate： - -- 澄清大需求目标、范围、明确不做、成功标准。 -- 读取 `.codestable/attention.md`、相关 requirements / architecture / compound / history features。 -- 写 `{slug}-roadmap.md` 和 `{slug}-items.yaml`。 -- 自查模块拆分、接口契约、依赖 DAG、最小闭环、safety net / polish / harden、验证入口、交付物、知识回写候选。 -- 运行 `cs-roadmap-review`，如果有 blocking / blocked，先修订或等待 reviewer；不要把未通过 review gate 的 roadmap 给用户确认。 -- 把完整 roadmap + items.yaml + `{slug}-roadmap-review.md` 给用户 review。 - -只有用户明确确认 roadmap 后，才进入所有 feature design 阶段。 - -### 第二次确认：所有 feature design - -对 roadmap items 里的每个 planned 子 feature，按依赖顺序逐个完成 `cs-feat-design` 的候选设计阶段： - -- 创建 feature 目录。 -- 写 `{feature-slug}-design.md`，frontmatter 带 `roadmap` / `roadmap_item`，正文按 `.codestable/attention.md` 的报告语言落盘（默认中文）。 -- 写 `{feature-slug}-checklist.yaml`。 -- 运行 `cs-feat-design-review`；Task agent 可用时每份 design-review 都必须有独立 reviewer 结果。批量生成多个 feature 不是 local-only 降级理由；有 blocking / blocked / pending 时先修订、等待 reviewer 或让用户明确授权降级，不进入用户二次确认。 -- 按现有 `cs-feat-design` 约定，把 items.yaml 对应条目更新为 `in-progress` 并填写 `feature` 字段。 -- design 必须包含：基线预检、必跑验证命令、交付物、验收场景证据类型、清洁度规则、可独立验证 steps。 - -这里把 `cs-feat-design` 普通模式里的单 feature 用户整体 review 推迟到本技能统一处理：每份 design 先保持 `draft`，不要逐个改 `approved`。全部 feature design 都写完且 design-review 都 passed 后，一次性给用户 review。用户可能反复修改任意一个 design；每次修改后同步更新 checklist，并对实质变化重跑 `cs-feat-design-review`。只有用户明确确认所有 design 后，才输出 `/goal`。 - -用户确认所有 design 后，先把每份 `{feature-slug}-design.md` 的 frontmatter `status` 从 `draft` 改为 `approved`，再生成 goal 执行包。`cs-feat-impl` 和 `cs-feat-accept` 都要求 design 已 approved；不要把 draft design 交给 goal 会话。 - ---- - -## 生成 goal 执行包 - -在 `.codestable/roadmap/{slug}/` 内写： - -### `goal-plan.md` - -包含： - -- roadmap 路径和 items.yaml 路径 -- feature 执行顺序 -- 每个 feature 的一句话交付物 -- 每个 feature 的性质：functional / non-functional / mixed -- roadmap 级核心验收路径：必须真实运行的用户 / API / CLI / 后端 / e2e / smoke 场景；没有则写 none，并说明为什么这是纯非功能性 roadmap -- 关键假设 -- Top 3 风险与缓解 -- 必跑验证命令集合 -- 最终聚合测试命令集合：roadmap 完成前必须重跑的 build / typecheck / lint / unit / integration / e2e / smoke；纯非功能性 roadmap 可用静态 / 一致性 / schema / 文档校验替代，但要写理由 -- 预检策略 -- DoD Policy、Gate Policy、Provider Policy -- Provider Policy 必须写明 archguard / meta-cc unavailable 记录 fallback，不自动阻塞；provider warning 需由 review / QA / audit 解释 -- 验证工具缺失时的恢复策略：只能补测试依赖、锁文件或既有 runner 配置，不能新增同名 shim 或伪造验证结果 -- 最终审计会核验的交付物类型 -- 最终审计必须运行 `codestable-goal-consistency-gate.py --roadmap {roadmap-path}` -- 最终审计会聚合 goal-evidence-summary、provider warnings、E/C/H summary 和 H-only core checks - -### `goal-state.yaml` - -生成前必须先探测 git 基线： - -1. 运行 `git rev-parse --is-inside-work-tree`。 -2. 返回 `true` 时，运行 `git rev-parse HEAD`，把得到的 SHA 写入 `baseline_ref`。 -3. 返回非 git 仓库时，`baseline_ref: no-git`。 -4. 在 git 仓库内但无法取得 HEAD 时，先停止并修复基线（例如还没有任何提交），不要写 `no-git` 伪装成非 git 仓库。 - -格式： - -```yaml -roadmap: "{slug}" -status: ready-to-dispatch -baseline_ref: "{git rev-parse HEAD 或 no-git}" -current_feature_index: 0 -features: - - slug: "{feature-slug}" - roadmap_item: "{feature-slug}" - feature_dir: ".codestable/features/YYYY-MM-DD-{feature-slug}" - design: ".codestable/features/YYYY-MM-DD-{feature-slug}/{feature-slug}-design.md" - checklist: ".codestable/features/YYYY-MM-DD-{feature-slug}/{feature-slug}-checklist.yaml" - review: ".codestable/features/YYYY-MM-DD-{feature-slug}/{feature-slug}-review.md" - qa: ".codestable/features/YYYY-MM-DD-{feature-slug}/{feature-slug}-qa.md" - acceptance: ".codestable/features/YYYY-MM-DD-{feature-slug}/{feature-slug}-acceptance.md" - status: pending -``` - -`current_feature_index` 是 **0-based**，指向 `features` 数组中下一个要处理的元素；第一个 feature 必须是 `0`。每个 feature accepted 后必须 scoped-commit 且确认工作树干净，再加 1。展示给用户的 `Feature: N/总数` 仍使用 1-based。roadmap item 若在执行前被标 `dropped`，不要写入 `goal-state.features`；已进入 `goal-state.features` 的条目必须走到 `accepted` 或回退修复。 - -### `goal-protocol*.md` - -从 `references/protocol.md`、`protocol-feature-loop.md`、`protocol-gates.md`、`protocol-audit.md` 复制到 roadmap 目录，并把 `{roadmap-slug}` / `{roadmap-path}` / `{roadmap-file}` / `{items-file}` 替换为本次实际值。不要替换 `` 这类运行时占位；它们必须保留给 goal 会话在每个 feature 边界填写。 - -`goal-protocol-gates.md` 是 Gate Policy 的运行时权威入口；`scope-gate`、`dod-runner`、`evidence-pack` 等具体脚本由 `cs-onboard` 安装到项目 `.codestable/tools/`。缺脚本时先刷新 onboard 骨架，不要把缺失脚本当作 gate passed。 - -### `goal-features/{feature-slug}.md` - -每个 feature 一份，包含： - -- 对应 roadmap item -- design / checklist / design-review / review / QA / acceptance 路径 -- 依赖项 -- feature 性质：functional / non-functional / mixed -- 核心运行路径：功能性 feature 必填；非功能性 feature 写 none + 替代证据 -- 必跑命令 -- Feature DoD、stage gates、gate 输入产物、失败恢复路径 -- 验收证据 -- 交付物 -- 清洁度规则 -- 失败恢复边界 - ---- - -## 自查 - -输出 `/goal` 前必须自查并修正： - -1. roadmap items 是否 DAG，无循环依赖。 -2. 每个 item 是否已有 design + checklist。 -3. roadmap review 是否存在且 `status: passed`，没有 unresolved blocking finding。 -4. 每个 item 是否已有 design-review 且 `status: passed`，没有 unresolved blocking finding，并记录已完成独立 reviewer 或用户明确降级。 -5. 每份 design 是否已 `status: approved`，且 frontmatter 的 `roadmap` / `roadmap_item` 与 items.yaml 一致。 -6. 每个 checklist step 是否可独立验证，且初始 `steps.status` 为 `pending`、`checks.status` 为 `pending`。 -7. 每个 feature 是否有必跑命令 / 基线风险 / 交付物 / 清洁度规则。 -8. 每个 goal-feature spec 是否写明 design-review / review / QA / acceptance 产物路径，以及 review blocking / QA failed 的返回路径。 -9. `goal-state.yaml` 是否能断点恢复，且 `current_feature_index` 使用 0-based 语义。 -10. `goal-plan.md` 是否写明 roadmap 级核心验收路径、最终聚合测试命令、非功能性替代证据策略、DoD Policy、Gate Policy、Provider Policy。 -11. 用户是否已明确确认 roadmap 和所有 feature design。 -12. `goal-protocol*.md` 是否都低于 300 行，且没有把 roadmap slug 误替换进 feature 标记；`Feature:` 行必须使用 `` 或真实当前 feature slug。 -13. 验证命令如果依赖外部测试工具，goal-plan / goal-feature spec 是否说明真实 runner 或依赖安装方式；不能通过新增 `pytest.py`、`jest`、`go` 等同名 shim 绕过。 -14. 最终审计是否能从仓库事实核验每个交付物，运行 goal consistency gate，并会落盘到 `{roadmap-path}/goal-audit.md`。 - ---- - -## 输出给用户的 goal 指令 - -确认通过后，读取 `references/goal-command-template.md`，替换 `{slug}`，打印一条 fenced `/goal`，然后停止。 - -只输出指令，不替用户执行；slash command 只能由用户粘贴触发。 - ---- - -## 完成判据 - -本技能阶段完成于：用户拿到可直接粘贴的 `/goal` 指令。 - -真正的 roadmap 完成由 goal 会话负责，必须满足： - -- 所有 goal-state features 状态为 `accepted` -- roadmap items 全部 `done` 或带理由 `dropped` -- 每个 feature 有 review 报告，且无 unresolved blocking findings -- 每个 feature 有 QA 报告，且无 unresolved failed / blocked items -- 每个 feature 有 acceptance 报告 -- `{roadmap-path}/goal-audit.md` 存在，记录最终聚合测试、roadmap 级核心验收路径、跳过项、re-verified / trust-prior 和结论 -- architecture / requirement / roadmap 回写完成 -- 最终审计通过 -- 已做 learning reflection：筛出 pitfall / knowledge 候选，并建议用户确认后再运行 `cs-keep` -- 已提示用户可运行 `cs-docs-neat`，同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 -- transcript 打印 `CS_ROADMAP_GOAL_COMPLETE` - -注意：goal 会话只自动做学习点反思和候选筛选，不自动写 `.codestable/compound/`。长期知识库归档必须由用户确认后触发 `cs-keep`，按它自己的查重、提炼、review、归档流程执行。 - ---- - -## 资源 - -写 `goal-protocol*.md` 时读取 `references/protocol.md`、`references/protocol-feature-loop.md`、`references/protocol-gates.md`、`references/protocol-audit.md`。输出 slash command 时读取 `references/goal-command-template.md`。 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-epic` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-roadmap-impl-goal/references/goal-command-template.md b/plugins/codestable/skills/cs-roadmap-impl-goal/references/goal-command-template.md deleted file mode 100644 index 0f80600..0000000 --- a/plugins/codestable/skills/cs-roadmap-impl-goal/references/goal-command-template.md +++ /dev/null @@ -1,7 +0,0 @@ -# Roadmap Goal 指令模板 - -`cs-roadmap-impl-goal` 在完成两次用户确认、写完 goal 执行包并自查通过后，按本模板输出 fenced `/goal`。替换 `{slug}`，保留 `{feature-slug}` 运行时占位。 - -```text -/goal "执行 CodeStable roadmap 目录 .codestable/roadmap/{slug} 下的 goal 执行包。先读取 goal-protocol.md、goal-protocol-feature-loop.md、goal-protocol-gates.md、goal-protocol-audit.md、goal-state.yaml、goal-plan.md；这是已由用户确认 roadmap 和全部 feature design 后的 goal 模式，按 goal-plan.md 的 Gate Policy 与 goal-protocol-gates.md 的 gate 接管规则执行。按 goal-state.yaml 的 features 顺序循环处理每个 feature：读取 goal-features/{feature-slug}.md、对应 design 和 checklist，完成 cs-feat-impl，再完成 cs-code-review；如果 review 有 blocking findings，按 review-fix 修复后重跑 cs-code-review；review passed 后完成 cs-feat-qa；如果 QA failed / blocked，按 qa-fix 修复后重跑 cs-code-review 和 cs-feat-qa；QA passed 后完成 cs-feat-accept，并更新 goal-state.yaml 与 roadmap items。每个 feature 验证通过后打印 CS_ROADMAP_GOAL_FEATURE_DONE。所有 feature 完成后，按 goal-protocol-audit.md 做最终 roadmap 审计。只有当 CS_ROADMAP_GOAL_COMPLETE 出现在 transcript 中，且所有 feature 都已 review passed、QA passed 且 accept、最终审计通过、没有 CS_ROADMAP_GOAL_HANDOFF，本 goal 才算完成。" -``` diff --git a/plugins/codestable/skills/cs-roadmap-review/SKILL.md b/plugins/codestable/skills/cs-roadmap-review/SKILL.md index d40e1c6..ce90379 100644 --- a/plugins/codestable/skills/cs-roadmap-review/SKILL.md +++ b/plugins/codestable/skills/cs-roadmap-review/SKILL.md @@ -1,283 +1,23 @@ --- name: cs-roadmap-review -description: Roadmap review gate。触发：人审前审 roadmap/items，或用户要求规划审查。 +description: Epic review 兼容入口。旧 roadmap review 调用保留；执行时转入 cs-epic 主流程的 review 阶段。 --- # cs-roadmap-review -## 启动必读 +本技能是 `cs-epic` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_stage: review` -本阶段是 roadmap 交给用户人工确认前的规划审查 gate。它只读 roadmap、items、相关文档和必要代码事实，只写 `{slug}-roadmap-review.md`，不直接改 roadmap、不替用户批准 roadmap、不推进 feature design。 +## 执行规则 -目标不是追求"规划看起来完整"，而是确认这份 roadmap 已经具备让用户有效 review 的条件：目标可证伪、范围边界清楚、模块拆分与接口契约可执行、子 feature 可独立验证、依赖 DAG 合理、风险和验证策略提前暴露。 +1. 按已安装 skill 名称加载 `cs-epic` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-epic` 主协议继续执行，并带上入口意图 `requested_stage: review`。 +3. 不要要求用户重新调用 `cs-epic`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。roadmap 的具体结构以目标 `{slug}-roadmap.md` / `{slug}-items.yaml` 和项目内共享口径为准。 -> 报告语言：roadmap-review 报告正文必须按 `.codestable/attention.md` 用**中文**；若草稿用了英文，落盘前先改写为中文。frontmatter / yaml 字段不翻译。 +## 维护规则 ---- - -## 输入 - -进入 review 前必须读取： - -- `.codestable/attention.md` -- `.codestable/roadmap/{slug}/{slug}-roadmap.md` -- `.codestable/roadmap/{slug}/{slug}-items.yaml` -- roadmap 目录下相关 `drafts/` 材料（只读与本次候选直接相关的） -- roadmap frontmatter 指向的 requirement / architecture 文档 -- roadmap 第 7 节观察项提到的相关文档 -- 相关 compound 沉淀：用项目搜索工具按大需求关键词检索 decision / learning / explore / trick -- items.yaml 中已存在 `feature` 字段的 feature design / acceptance（update 模式或复审时） -- roadmap 中接口契约或模块拆分引用到的关键代码位置 -- 独立 Task agent reviewer 输出（如果本轮已启动） - -没有代码引用时不强行扫全仓库；但 roadmap 声称复用现有模块、接口、命令、配置或数据结构时，必须读对应代码或文档事实核验。 - ---- - -## 启动检查 - -1. roadmap 主文档存在，frontmatter `doc_type=roadmap`，`slug` 与目录一致，`status` 是 `draft|active|paused|completed` 之一。 -2. items.yaml 存在，`roadmap` 与 slug 一致，`items` 非空。 -3. items.yaml 每条有 `slug` / `description` / `depends_on` / `status` / `feature` / `minimal_loop`。 -4. 依赖图能解析；有循环、自指、未知依赖时直接列 blocking。 -5. 如果已有 `{slug}-roadmap-review.md`： - - `status: passed` 且 roadmap/items 未变化：提示可进入用户 review。 - - `status: changes-requested` / `blocked`：读取旧 findings，确认是否复审。 - - roadmap/items 已变化：重新 review，并在报告里记录轮次。 - ---- - -## 独立 Task agent reviewer gate - -本阶段必须优先启动独立 Task agent reviewer；当前 agent 的本地审查只能作为合并与事实核验，不能替代独立审查。只有运行时确实没有 Task agent 能力、provider 不可用且无法配置，或用户在看到降级风险后明确授权，才允许 `local-only` / `skipped-by-user`。批量 roadmap、赶时间、主 agent 自认为风险低，都不是降级理由；需要授权降级时，先按 `.codestable/reference/approval-conventions.md` 写 `approval-report.md`，再让用户选择。 - -一旦本轮应该启动或已经启动独立 Task agent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 reviewer 返回前定稿 `{slug}-roadmap-review.md`、不能给出 `passed`、不能把 roadmap 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。 - -**检测由主 agent 在运行时自检自己的工具**，不靠脚本猜环境——主 agent 最清楚自己手上有哪些工具。按 Task agent 选择规则启动独立 Task agent reviewer（优先 Paseo subagent，否则当前宿主原生 Codex/Claude Task/Agent）： - -1. **有 `mcp__paseo__create_agent` 工具**：必须优先用 Paseo subagent 做只读独立审查（首选：能换 provider，做到真正异构审查）。启动前先加载 / 读取 `paseo` skill 的当前说明，并遵守它的规则：读取 `~/.paseo/orchestration-preferences.json`，使用 `providers.audit`，不要硬编码 Claude 或 Codex。不要无限轮询运行中的 agent；如果 reviewer 已启动但结果未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。 -2. **否则有当前宿主原生 Codex/Claude Task/Agent 工具**：用原生 Task agent 做独立上下文审查。如属同类 agent，在报告里记录降级和残余风险。 -3. **两者都没有**：本地 review 只能在记录 `local-only` 且获得必要授权后定稿；没有授权时报告 `blocked`，不要伪装启动。 - -独立 Task agent reviewer prompt 必须只给原始材料和边界，不透露本地 review 结论： - -```text -你是 CodeStable roadmap 的独立规划审查 agent。只读，不修改文件，不更新 roadmap/items。 - -请读取： -- .codestable/attention.md -- {roadmap_path} -- {items_path} -- roadmap frontmatter 指向的 requirement / architecture 文档 -- roadmap 相关 compound / draft 材料 -- roadmap 引用到的关键代码或命令入口 - -按 cs-roadmap-review 的严重度语义输出：blocking / important / nit / suggestion / learning / praise / residual-risk。 -重点审查：目标完成信号、范围与明确不做、模块拆分、interface depth / seam placement / adapter、接口契约可执行性、子 feature 原子性、依赖 DAG、最小闭环、验证策略、风险缓解、知识回写点、用户是否能据此有效拍板。 -每条 finding 必须有 roadmap/items/doc/code 事实证据、影响、建议修复边界。 -不要写 {slug}-roadmap-review.md；只把审查结果回传给主 agent。 -``` - -主 agent 仍是最终审查责任方：必须逐条核验独立 Task agent reviewer 的 finding，去重、定级、合并进 `{slug}-roadmap-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。 - ---- - -## 审查流程 - -### 1. 范围与事实 - -- 用 roadmap 第 1/2 节确认目标、覆盖范围、明确不做、关键假设。 -- 用第 3/4 节确认模块拆分和接口契约是否足够支撑多个 feature 共用。 -- 用第 5 节和 items.yaml 对齐所有子 feature：slug、描述、所属模块、依赖、状态、feature 绑定、minimal_loop。 -- 用相关 req / arch / compound 判断有没有冲突、重复规划或遗漏约束。 -- 用代码事实核验 roadmap 对现有模块、命令、接口、配置、数据结构的描述。 - -### 2. 独立审查合并 - -- 记录主 agent 自检结果：`paseo` / `native-agent` / `local-only`。 -- 没有启动独立 Task agent reviewer 时，记录确无能力 / provider 不可用 / 用户授权降级；未满足这些条件时不得定稿 `passed`。 -- 启动 Paseo subagent / 原生 Task agent 后，最终 verdict 必须等 reviewer 返回。 -- reviewer 返回后逐条做本地事实核验；能用文档 / 代码 / items 证据支撑才合并。 -- reviewer 失败、权限阻塞、超时或仍在运行时，不要默默降级；报告 `status: blocked`。 - -### 3. 规划审查 - -至少覆盖： - -- 目标完成信号：是否能观察、能验收、能判定完成 / 未完成。 -- 范围与明确不做：是否具体，能否防止后续 feature 偷偷扩范围。 -- 模块拆分：职责是否清楚，是否有重复模块、万能模块、遗漏模块。 -- Module/interface 设计：是否制造 pass-through module；跨模块 interface 是否 deep；seam / adapter 是否真实需要；dependency strategy 是否支撑后续测试。 -- 接口契约：是否写到函数签名 / 数据结构 / 协议字段 / 错误码级别；无跨模块接口时是否明确写明。 -- 子 feature 原子性：每条能否独立 design / implement / review / QA / accept；描述是否可证伪。 -- 依赖 DAG：是否无环，依赖理由是否具体，最弱依赖是否先验证。 -- 最小闭环：第一条或最小路径做完后是否能端到端演示。 -- 验证与基线：是否识别 build / typecheck / lint / test / e2e / 手工验证入口；基线不稳时是否安排 safety net。 -- 风险与恢复：Top 风险、外部依赖、迁移 / 权限 / 安全 / 回滚是否提前暴露。 -- 交付物与知识回写：后续 acceptance 是否能从仓库事实核验产物；稳定约定 / 坑点是否有沉淀候选。 - -### 4. Roadmap Review Invariants 与证据分级 - -每轮 review 必须形成 Evidence Confidence Ledger。证据分级只描述依据来源，不计算质量分： - -- `E` Embedded：roadmap / items.yaml / checklist / 命令输出里直接可见。 -- `C` Context：相关 req / arch / compound / 代码事实支撑。 -- `H` Heuristic：工程经验或 reviewer 判断，缺少直接仓库证据。 - -核心 invariants： - -- Granularity Gate 能解释为什么进入 roadmap，而不是 single feature / brainstorm。 -- Goal Coverage Matrix 中每个核心完成信号都有 item、验证入口和 evidence type。 -- items.yaml 仍是 DAG，且最小闭环可独立验收。 -- 接口契约可被 feature-design 当硬约束。 -- 跨模块 interface 有 depth / seam / dependency strategy 依据；无跨模块接口时明确 not-applicable。 -- 核心检查若只有 `H` 证据，不能静默 `passed`；至少写入 residual risk，必要时列 important / blocking finding。 - ---- - -## 严重度 - -- `blocking`：必须先修。会导致用户无法有效 review、feature 不能独立执行、接口契约不可用、依赖循环、明显违反 req / arch、关键风险未覆盖、验收不可证伪。 -- `important`：应该修；若用户决定延后，必须在 roadmap review 和用户 review 摘要中明确记录。 -- `nit`：小的清晰度或一致性建议，不阻塞。 -- `suggestion`：替代拆法或补强思路，不要求本次采用。 -- `learning`：知识性说明，不要求动作。 -- `praise`：记录值得保留的规划做法；少量即可。 -- `residual-risk`：review 无法完全消除的不确定性，需要用户 review 或后续 feature-design 重点复核。 - -不要把个人偏好的拆法升级成 blocking。blocking 必须能用 roadmap 契约、items 事实、相关文档、代码事实或可靠工程原则支撑。 - ---- - -## 报告模板 - -报告路径：`.codestable/roadmap/{slug}/{slug}-roadmap-review.md`。 - -```markdown ---- -doc_type: roadmap-review -roadmap: {slug} -status: passed|changes-requested|blocked -reviewed: YYYY-MM-DD -round: 1 ---- - -# {slug} roadmap 审查报告 - -## 1. Scope And Inputs - -- Roadmap: {path} -- Items: {path} -- Related docs: {requirements / architecture / compound / drafts} -- Code facts checked: {paths / none} - -### Independent Review - -- Status: not-available|skipped-by-user|local-only|pending|completed|failed|blocked -- Detection: paseo|native-agent|local-only|skipped -- Provider / agent: {providers.audit / agent id / none} -- Raw output: {摘要 / 路径 / none} -- Merge policy: {已逐条核验 / 未启用原因 / pending 时不得定稿} -- Gate effect: {none | blocks final verdict until completed / user-approved downgrade} - -## 2. Roadmap Summary - -- Goal completion signal: {摘要} -- Module split: {摘要} -- Interface contracts: {摘要} -- Items: {数量 + minimal loop + 风险热点} -- Dependency shape: {DAG / 问题} - -## 3. Findings - -### blocking - -- [ ] RMR-001 `{path#section|items.slug|file:line}` {问题} - - Evidence: {事实} - - Impact: {为什么阻塞用户 review / 后续 feature} - - Expected fix scope: {修复边界} - -### important - -- [ ] RMR-00N `{证据位置}` {问题} - - Evidence: {事实} - - Impact: {影响} - -### nit - -- [ ] RMR-00N `{证据位置}` {建议} - -### suggestion - -- [ ] RMR-00N {建议} - -### learning - -- {可复用规划经验或注意点} - -### praise - -- {值得保留的做法} - -## 4. User Review Focus - -- 用户需要重点拍板：{决策 / 假设 / 优先级} -- 后续 feature-design 需要重点复核：{接口 / 风险 / 验证} -- 不能靠 roadmap review 完全确认的点：{列表} - -## 5. Evidence Confidence Ledger - -| Check | Verdict | Evidence Class | Basis | Follow-up | -|---|---|---|---|---| -| Granularity Gate | pass|warn|fail | E|C|H | {路径 / 事实 / 判断依据} | {none / 复核点} | -| Goal Coverage Matrix | pass|warn|fail | E|C|H | {依据} | {复核点} | -| DAG and minimal loop | pass|warn|fail | E|C|H | {依据} | {复核点} | -| Interface contract usability | pass|warn|fail | E|C|H | {依据} | {复核点} | -| Module interface depth | pass|warn|fail|n/a | E|C|H | {依据} | {复核点} | - -Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。 - -## 6. Residual Risk - -- {风险 + 用户 review / feature-design 如何处理；没有写 none} - -## 7. Verdict - -- Status: passed|changes-requested|blocked -- Next: 交给用户 review | 回 `cs-roadmap` 修订后重跑 `cs-roadmap-review` | 等独立 Task agent reviewer 完成 / 用户确认降级后重跑 -``` - -没有某类 finding 时写 `none`，不要删除章节；下一轮复审要能对比。 - ---- - -## 退出条件 - -- [ ] 已读取 attention、roadmap、items、相关 req / arch / compound / drafts。 -- [ ] 已按 roadmap 声明核验必要代码或命令事实。 -- [ ] 已确认 items.yaml 可解析，依赖图无未知节点；有问题已列 finding。 -- [ ] 已按 Task agent 选择规则启动独立 reviewer；若未启动，已记录确无能力 / provider 不可用 / 用户授权降级。 -- [ ] 如果启动了独立 Task agent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。 -- [ ] 已审查目标、范围、模块、接口、feature 原子性、依赖、最小闭环、验证、风险、知识回写。 -- [ ] 已检查 Granularity Gate、Goal Coverage Matrix 和 Roadmap Review Invariants。 -- [ ] 已写 Evidence Confidence Ledger；核心检查 H-only 时没有静默 passed。 -- [ ] 已写 `.codestable/roadmap/{slug}/{slug}-roadmap-review.md`。 -- [ ] 有 blocking / 未处理 important 时指向 `cs-roadmap` 修订并重跑 review。 -- [ ] 无 blocking 且 important 已处理或明确接受时，明确告诉用户下一步是 roadmap 人工 review。 - ---- - -## 容易踩的坑 - -- 把 roadmap review 做成语病检查，没审接口契约和依赖图。 -- 只读主文档，不核对 items.yaml。 -- 不读 requirement / architecture，导致规划和现状冲突没发现。 -- 接口契约写着"待定"也放过，后续每条 feature 各自发明接口。 -- 子 feature 里塞多个可独立验收的交付，却只当一条。 -- 把批量 roadmap 或赶时间当成 local-only 降级理由。 -- 启动独立 Task agent reviewer 后结果还没回来，就把本地 review 定稿为 passed。 -- 外部 reviewer 的结论没经本地事实核验就照抄。 -- review 报告没有落盘，导致用户 review 和后续 design 没有可追溯输入。 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-epic` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs-roadmap/SKILL.md b/plugins/codestable/skills/cs-roadmap/SKILL.md index 9a5bac2..e60305d 100644 --- a/plugins/codestable/skills/cs-roadmap/SKILL.md +++ b/plugins/codestable/skills/cs-roadmap/SKILL.md @@ -1,277 +1,23 @@ --- name: cs-roadmap -description: Roadmap 规划。触发：需求大到需要拆 feature，或用户说拆需求/开 roadmap。 +description: Epic planning 兼容入口。旧 roadmap 调用保留；执行时转入 cs-epic 主流程的 planning 阶段。 --- # cs-roadmap -## 启动必读 +本技能是 `cs-epic` 的长期兼容入口，不维护独立流程规则。 -开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 +入口意图：`requested_stage: planning` -`.codestable/roadmap/` 是项目的"规划层"——每个子目录承载一块大需求，主文档由三块构成： +## 执行规则 -1. **概设**：这块大需求要怎么搭、拆成哪几个模块 / 组件、各自职责 -2. **架构层详设**：模块之间的接口契约、共享数据结构、跨 feature 的协议 -3. **子 feature 拆解**：把方案分解成一串带依赖关系的子 feature 种子，feature 流程一次消费一条 +1. 按已安装 skill 名称加载 `cs-epic` 作为权威主协议，不把兄弟目录相对路径当作主路径。 +2. 在当前 run 按 `cs-epic` 主协议继续执行，并带上入口意图 `requested_stage: planning`。 +3. 不要要求用户重新调用 `cs-epic`。 +4. 如果当前运行时无法加载主入口协议，停止并报告兼容入口不可继续。 -三块**一起**作为这块大需求所有子 feature 的共同约束——每条子 feature 进 `cs-feat-design` 时，roadmap 第 2 块的接口契约就是它的**硬约束输入**（不能违反，要改先回 roadmap update）。 +## 维护规则 -当 roadmap 涉及跨模块 module interface、seam、adapter 或依赖替身策略时，按 `references/codebase-design.md` 做内嵌 deep-module 检查；这不是切换到独立 `codebase-design` skill。 - -**为什么 roadmap 不直接写 ADR**：ADR（`requirements/adrs/`）记的是"已经拍板的稳定结构性决策"，roadmap 记的是"还没落地、可能还会变"的前瞻性接口契约。等子 feature 真正落地、对应接口稳定后，由 `cs-feat-accept` 盘点出来的领域影响触发 `cs-domain` 写 ADR——roadmap 完成过渡使命后归档。 - -**为什么单独一层**：requirements 记"要什么 + 怎么定义术语 + 拍板了哪些决策"（愿景 + 领域），roadmap 记"怎么分步实现"（执行）。把执行规划塞进 requirements 会把"要什么"和"打算怎么实现"混起来。 - -**为什么文件夹不是单文件**：拆解过程会产生草稿 / 调研 / 方案对比 / 白板转述，塞一份 md 会乱又舍不得删。每个 roadmap 一个子目录，主文档对外口径，旁边 `drafts/` 随便堆。 - -**规划原则**：roadmap 不是"任务列表"，而是一次可执行路线设计。动笔前要先把目标、约束、风险、依赖、可验证完成信号想清楚；拆出来的每条子 feature 都要能独立验证；整份 roadmap 交给用户前必须先做一次自我批判，修掉含糊验收、错误依赖和被打包过大的条目。 - -**推进原则**：一个长期软件任务能不能稳步推进，取决于有没有把"当前状态 → 下一步 → 验证 → 修复 → 记录"闭环设计清楚。roadmap 阶段要提前识别基线是否可能已坏、哪些条目承担 safety net / polish / harden、哪些产物必须落盘、哪些经验要回写到 CodeStable 知识层。没有这些，后续 feature 只是顺序执行，不是可恢复、可审计的推进。 - -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。主文档和 items 完整模板看同目录 `reference.md`。 - ---- - -## 适用场景 - -- 用户描述"一眼看出做不完"的大需求（"加权限系统"、"做通知中心"、"接 SSO"） -- `cs-brainstorm` 判为 case 3 移交过来（brainstorm 只做分诊，不做拆解） -- 已有 roadmap 加新子 feature / 改依赖 / 调顺序 / 标废弃 -- feature-design 发现要做的事实际是多个 feature 集合，先退回拆 - -不适用：单 feature 能装下 → `cs-feat`；描述能力"是什么、边界" → `cs-req`；拍板长期规约 / 架构选型 / 加术语 → `cs-domain`；操作性沉淀 → `cs-keep`。 - ---- - -## 模式分流 - -| 用户说什么 | 模式 | -|---|---| -| "拆一下 X 需求"、"开一份 X 的 roadmap"、"我想要一个 X 系统" | `new` | -| "往 {已有 roadmap} 加子 feature"、"重排顺序"、"标 drop" | `update` | - -判断不出问用户。 - ---- - -## 单目标规则 - -每次只动一份 roadmap。一次扔出"我想要 X 和 Y"先选一个，另一个下次。理由同 req / arch——一次吐多份用户 review 不过来。 - ---- - -## 目录结构 - -``` -.codestable/roadmap/{slug}/ -├── {slug}-roadmap.md 主文档：背景 / 范围 / 模块拆分（概设）/ 接口契约（架构层详设）/ 子 feature 清单 / 排期 -├── {slug}-items.yaml 机器可读清单（feature-design 读、feature-acceptance 回写） -├── {slug}-roadmap-review.md 独立规划审查报告（人审前 gate） -└── drafts/ 可选，调研 / 讨论 / 草稿 -``` - -`{slug}` 小写字母 / 数字 / 连字符，和大需求一致（`permission-system`、`notification-center`）。平铺不嵌套 epic / sub-epic。`drafts/` 按需建，AI 不强制归档。 - ---- - -## 工作流 - -### Phase 1：锁定目标 - -模式 + 目标 + 范围。new 模式先敲定一个英文 slug（参考现有 req / arch slug 习惯）。 - -### Phase 2：读取材料 - -**共同必读**：`.codestable/attention.md` + 用户素材 + `roadmap/` 其他 roadmap（防重复）+ `requirements/` 相关 req + `requirements/CONTEXT.md` + `requirements/adrs/` 相关 ADR。 - -**按情况读**： -- 相关 compound 沉淀：`grep -r "{大需求关键词}" .codestable/compound/` -- 已有相关 feature 方案 -- 项目可用验证命令 / 已知基线：从 `.codestable/attention.md`、架构 doc、历史 acceptance、README / package scripts / CI 配置里找 build / typecheck / lint / test / e2e / 浏览器验证入口。roadmap 不直接跑完整命令，但要知道后续每条 feature 靠什么验证 - -**update 额外**：当前主文档全文 + items.yaml 当前状态 + 已启动 / 完成的子 feature 的 design / acceptance。 - -### Phase 3：拆解与起草 - -按 `reference.md` "主文档结构"和"items.yaml 格式"写**完整初稿**不分批。 - -先做 **Granularity Gate**：确认本需求为什么应该进入 roadmap，而不是 single feature 或 brainstorm；结论写进主文档第 2 节，详细判据见 `reference.md`。 - -**先写深度规划底稿**（可写进主文档第 6 / 7 节，不必单独成文件）： - -- **目标完成信号**：这块大需求做到什么可观察状态才算完成，不写"能力完善"这种感受词 -- **Top 3 风险与缓解**：最可能翻车 / 最难回滚 / 最容易漏到上线后才发现的三件事，各自写清本 roadmap 怎么降低风险 -- **非显然依赖**：外部系统、数据迁移、现有模块约束、用户拍板项，哪些会卡住后续 feature -- **关键假设**：不是用户原话、但本次规划依赖它成立的判断；review 时让用户能精确反驳 -- **基线与验证入口**：后续 feature 应优先使用哪些命令 / 手工验证入口；如果当前仓库很可能缺测试或基线不稳，要在拆解里安排 safety net / characterization 条目 -- **交付物落点**：每条子 feature 完成后应该真实落在哪些代码 / 配置 / 文档 / roadmap 状态里，避免只在汇报里说完成 -- **知识回写点**：哪些约定、环境坑、跨 feature 规则如果被验证成立，应在 acceptance 收尾时沉淀到 attention / learning / decide / guide - -同时维护 **Goal Coverage Matrix**：每个 roadmap goal / completion signal 必须追踪到至少一个 item、验证入口和证据类型；没有可追踪项时先调整拆解，不把缺口留给后续 feature-design。 - -**拆解纪律**： - -0. **先做架构方案再拆 feature**——顺序：先想模块拆分（概设第 3 节）→ 模块间接口 / 数据结构 / 协议（详设第 4 节）→ 才把方案分解成子 feature（第 5 节）。**架构方案不清楚就硬拆 feature，结果是每个 feature 各自重新发明轮子、接口对不齐** -1. **接口契约要写到 feature 可拿来当硬约束的程度**——函数签名 / 数据结构 / 协议字段 / 错误码这一级，并说明 seam placement、dependency strategy 和 adapter 是否真实需要。讲不到这级回去想。无跨模块接口（如纯前端样式调整）就明确写"无跨模块接口" -2. **每条子 feature 能当独立 feature 流程跑完并独立验证**——能单独写 design / 实现 / 验收，完成后能拿出明确证据（命令、测试、截图、接口响应、文档归并）。跑不下来颗粒度不对 -3. **依赖图必须是 DAG**——A 依赖 B 写清楚，别循环 -4. **依赖关系要有具体理由**——"B 依赖 A，因为 A 提供 XX 表结构"而不是"A 先做" -5. **先列一条最小闭环**——做完后能端到端跑通最窄路径的标第一条 -6. **明确不做的边界**——用户脑子里的"权限系统"可能包括审计日志 / 数据脱敏，不打算覆盖就写进"明确不做" -7. **不替用户决定优先级**——技术依赖之外的排序让用户拍板 -8. **最后要有收口 / 硬化意识**——UI、全栈、权限、安全、迁移类大需求，如果前面条目只覆盖功能上线，要补一条收口型子 feature 或在最后一条里明确覆盖：错误态、空态、边界输入、安全、性能、回归扫尾、文档归并 -9. **条目数量由任务形态决定**——不要为了凑固定数量合并 / 拆散。能独立验证、交付一件 coherent thing 就是一条；名字里需要写"和 / 以及"通常说明塞了两条 -10. **验收词要可证伪**——每条子 feature 的描述和 notes 里不写"完善 / 优化 / 打通"这类空词，改成"输入 A 时得到 B"、"页面 X 展示 Y"、"命令 Z 通过" -11. **需要安全网时先建安全网**——brownfield 重构、迁移、核心路径改动、历史测试薄弱时，第一条或前几条应先补 characterization / baseline tests / 观测手段，再改行为 -12. **每条都要能断点续跑**——items.yaml 的 `status` / `feature` 是恢复锚点。条目 notes 里写清阻塞项、跳过原因、外部依赖，不靠对话记忆 - -### Phase 4：自查清单 - -独立 review 前自跑一遍汇报处理： - -1. 模块拆分讲清了吗？每个模块职责一句话能说出来？ -2. 接口契约写到可执行程度了吗？feature-design 看完不需要回来问就能直接照着实现？ -3. 每条子 feature 的 slug 规范？（grep `.codestable/features/` 确认不冲突） -4. 每条描述一句话讲清楚？讲不清就拆得不够或 scope 太模糊 -5. 依赖关系是 DAG？有没有自指 / A→B→A 回环 -6. 最小闭环真的最小？第一条做完能独立给用户演示点什么？ -7. "明确不做"有没有写？没写就说"没有明确不做" -8. 和已有 req / arch 有没有矛盾？有就写"和 req-X 冲突待用户决定"，不偷偷选边 -9. **update 专项**：本次新加 / 改条目都有素材依据？凭空"加一条让看起来更完整"是漂移 -10. **update 专项**：改了接口契约的话，已 in-progress / done 的子 feature 受影响吗？影响到的列"观察项"提示用户 -11. **可证伪性自查**：每条完成信号是不是 yes/no？有没有"体验更好 / 更稳定 / 支持完善"这类无法核对的词？ -12. **条目原子性自查**：有没有一条实际包含两个可独立验收的交付？名字或描述里出现"和 / 以及 / 同时"时重点复查 -13. **最弱依赖自查**：哪条失败会拖垮最多后续条目？它的前置验证和风险缓解是否足够早？ -14. **收口覆盖自查**：是否覆盖 polish / harden / regression sweep？如果没有，写清为什么本 roadmap 不需要 -15. **基线自查**：是否知道后续 feature 的验证入口？当前基线不稳 / 测试薄弱时是否安排了 safety net？ -16. **交付物自查**：每条做完后是否能从仓库事实看到产物，而不是只从汇报看到？ -17. **知识回写自查**：哪些规则或坑会影响后续 feature？是否放进观察项，等 acceptance 验证后触发对应沉淀流程？ -18. **Goal Coverage 自查**：每个 goal / completion signal 是否已映射到 item、验证入口和 evidence type？核心目标不能只靠模糊描述或后续再说。 -19. **Interface depth 自查**：跨模块接口是否 deep；是否有 pass-through module、假 seam 或单 adapter 间接层？ - -### Phase 5：候选落盘 + 独立 review gate - -先把候选稿写到标准 roadmap 目录，给 `cs-roadmap-review` 稳定输入： - -- **new**：建 `.codestable/roadmap/{slug}/`；写主文档 `status: draft`；写 items.yaml（每条 `status: planned`、`feature: null`）；`validate-yaml.py` 校验。 -- **update**：直接更新主文档 / items.yaml 的候选内容，结构性改动文末加变更日志；重新校验 yaml。 - -然后运行 `cs-roadmap-review`： - -- `passed`：才能把 roadmap 交给用户 review。 -- `changes-requested`：按 finding 修 roadmap/items，重新校验并重跑 `cs-roadmap-review`。 -- `blocked`：补齐输入、等待独立 Task agent reviewer，或让用户明确降级 local-only 后重跑。 - -### Phase 6：用户 review - -主文档 + items.yaml + `{slug}-roadmap-review.md` 完整贴给用户，并附上 Phase 4 自查结论、Top 3 风险与缓解、关键假设、review findings / residual risk。改到用户明确"可以了"。如果用户修改导致 roadmap/items 发生实质变化，回到 Phase 5 重跑 review gate。 - -### Phase 7：确认落盘 - -用户确认后，new 模式把主文档 `status` 改为 `active`、`last_reviewed` 改为当天；update 模式更新 `last_reviewed` 当天。重新校验 yaml。 - -**不改 requirements / architecture**——roadmap 是规划层，那两层只描述现状。拆解过程发现 req / 架构过时，在主文档"观察项"记一句给用户，不顺手改。 - -如果用户想把整份 roadmap 自动推进到底，确认落盘后提示下一步可以走 `cs-roadmap-impl-goal`：它会先完成所有子 feature design + design review，再让用户二次确认，最后输出可直接运行的 goal 指令。 - -确认落盘后再提示一句："这份 roadmap 已经改变了后续工作入口和文档索引，要不要做一轮文档与记忆整理？（`cs-docs-neat`）" 用户说不用就跳过；这是收尾引导，不是 roadmap 通过条件。 - ---- - -## 和 feature 流程的衔接 - -### feature 从 roadmap 起头 - -用户说"开始做 roadmap 里的 {子 feature}"时： - -1. `cs-feat-design`（或 ff / brainstorm）起 feature 目录 -2. design frontmatter 带 `roadmap: {slug}` + `roadmap_item: {子 slug}` -3. items.yaml 对应条目 `status: in-progress`、`feature: YYYY-MM-DD-{slug}` - -职责在 `cs-feat-design` 不在本技能。 - -### feature-design 必须把 roadmap 接口契约当硬约束 - -**roadmap 主文档第 4 节"接口契约"是 feature 的硬约束输入**——不是参考，是不能违反、要改先回 roadmap update。这就是为什么 roadmap 要在拆 feature 前先把架构方案定下来：让多条 feature 并行 / 串行实现时对外接口对齐。 - -feature-design 发现接口契约不合理 / 漏了 / 描述不准 → **回 `cs-roadmap update` 改了再继续**，不要在 feature 里偷偷绕开（绕开会让下一条同模块 feature 接到老契约导致二次冲突）。 - -### acceptance 自动回写 - -`cs-feat-accept` 收尾时如果 design frontmatter 有 `roadmap` 字段就改对应 `roadmap_item` 的 `status: done`，同时同步主文档子 feature 清单勾选状态。职责在 `cs-feat-accept` 不在本技能。 - -### roadmap 自身生命周期 - -- 所有 items `done` / `dropped` 后主文档 `status: completed`，目录留作历史档案 -- 长期无进展：`status: paused`，主文档加理由 - ---- - -## 硬性边界 - -1. **不写单 feature 内部实现细节**——roadmap 写到"模块边界 / 接口契约 / 共享协议"为止，单模块内部怎么实现归 feature-design。判据：**会被多个 feature 共同遵守**归 roadmap，**只在某个 feature 内部用**归 feature-design -2. **不改愿景和结构档案**——不顺手改 requirements / architecture / 代码 / 已有 feature。问题记"观察项" -3. **不替用户拍产品优先级**——技术依赖外的排序让用户决定 -4. **单目标**——一次只动一份 -5. **不发散**——用户范围外问题记观察项不扩大 -6. **接口契约要么可执行级要么明确"无跨模块接口"**——不允许"待定 / 后面再说"。含糊掉的接口在 feature-design 各条会各自补出来必然不一致 - ---- - -## 退出条件 - -- [ ] 已锁定单一模式 + 单一目标 -- [ ] 主文档 frontmatter 完整（`doc_type: roadmap` / `slug` / `status` / `created` / `last_reviewed` / `tags`） -- [ ] 主文档含：背景 / 范围与明确不做 / **模块拆分** / **接口契约** / 子 feature 清单 / 排期 / 观察项 -- [ ] 模块拆分节每个模块职责一句话讲清 -- [ ] 接口契约节写到 feature-design 可拿来当硬约束的级别（函数签名 / 数据结构 / 协议字段 / 错误码）或明确"无跨模块接口" -- [ ] 涉及跨模块 interface / seam / adapter 时，已记录 depth / locality / dependency strategy 和 adapter 结论 -- [ ] items.yaml 每条有 `slug` / `description` / `depends_on` / `status` / `feature` -- [ ] 依赖图是 DAG 无循环 -- [ ] 最小闭环条目已标 -- [ ] Top 3 风险、非显然依赖、关键假设已写入主文档或 review 摘要 -- [ ] 每条子 feature 都有可独立验证的完成信号 / 证据类型 -- [ ] 已完成 Granularity Gate 和 Goal Coverage Matrix；每个核心目标都能追踪到 item 与证据 -- [ ] 已做可证伪性 / 条目原子性 / 最弱依赖 / 收口覆盖自查并汇报 -- [ ] 已识别验证入口 / 基线风险；必要时拆出 safety net 条目 -- [ ] 每条子 feature 的交付物能被后续 acceptance 从仓库事实核验 -- [ ] 需要后续沉淀的 convention / learning / guide / attention 候选已写入观察项 -- [ ] items.yaml 通过 `validate-yaml.py` 校验 -- [ ] Phase 4 自查清单逐条跑过并汇报 -- [ ] `{slug}-roadmap-review.md` 已通过 `cs-roadmap-review`，没有 unresolved blocking finding -- [ ] 用户 review 通过 -- [ ] 没有顺手改 req / arch / 代码 / 已有 feature - ---- - -## 和其他工作流的关系 - -| 方向 | 关系 | -|---|---| -| `cs-req` 配合 | req 记"为什么有这个能力"、roadmap 记"打算怎么分步做出来"。大需求下可能多份 req；缺 req 提示用户先 `cs-req` | -| `cs-domain` 配合 | adrs/ 记已拍板决策、roadmap 记前瞻接口契约。读 ADR 理解现状但不改它 | -| `cs-feat` 下游 | 每条子 feature 是未来一次 feature 流程的种子；起头时 design frontmatter 带 `roadmap` / `roadmap_item` | -| `cs-feat-accept` 回写方 | acceptance 自动改 items.yaml 为 `done`，本技能只定义格式不负责回写 | -| `cs-roadmap-impl-goal` 下游 | 用户确认 roadmap 后，可把所有子 feature design 和后续 impl / review / QA / accept 编排成可恢复的 goal | -| `cs-onboard` 创建者 | 建 `roadmap/` 空目录 | -| `cs-brainstorm` 上游 | case 3 移交本技能，带"真问题 / 大致范围 / 可能子模块"一句话汇总。本技能不重复分诊直接拆 | - ---- - -## 常见错误 - -- **跳过架构方案直接拆任务**——上来就列子 feature，模块边界 / 接口没想，feature-design 各自发明轮子 -- **接口契约写得含糊**——"两边商量"、"待定"、"用一个统一的事件总线"——讲不到字段 / 签名 / 协议级。feature-design 接到这种没法当硬约束 -- 制造 pass-through module 或只有一个 adapter 的假 seam——看似解耦，实际只是多一层同步成本 -- 把单 feature 内部细节写进 roadmap（某模块内部怎么分文件 / 用哪个库）——归 feature-design -- 颗粒度失衡——一条装得下三个独立功能、另一条只改个配置 -- 依赖关系靠脑补——讲不清为什么依赖 -- 替用户排优先级 -- 和已有 req / arch 冲突不停下——自己选一边掩盖真实分歧 -- 一次做多份 roadmap -- 顺手改 req / arch -- drop 条目直接删——历史丢失 -- roadmap 跑偏成给单条子 feature 写详细方案 -- update 改接口契约不评估存量影响——已 in-progress / done 的 feature 没人看到契约变了 -- 跳过 `cs-roadmap-review` 直接让用户拍板——用户只能看到规划表面，看不到接口、依赖、验收策略的独立审查结论 +- 不在本文件复制阶段流程、模板或 gate 规则。 +- 规则变更只更新 `cs-epic` 及其 `references/`。 +- 本入口只用于保持旧调用、旧提示词和历史习惯可用。 diff --git a/plugins/codestable/skills/cs/SKILL.md b/plugins/codestable/skills/cs/SKILL.md index 9e58f81..d3dba92 100644 --- a/plugins/codestable/skills/cs/SKILL.md +++ b/plugins/codestable/skills/cs/SKILL.md @@ -1,6 +1,7 @@ --- name: cs description: CodeStable 路由入口。触发：用户只说 cs/该用哪个 skill/介绍体系，或诉求未收敛。 +argument-hint: "[诉求描述，可空]" --- # cs @@ -9,208 +10,117 @@ description: CodeStable 路由入口。触发：用户只说 cs/该用哪个 ski 开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。 -`cs` 是 CodeStable 工作流家族的统一入口。用户开口大概率不会指名某个 `cs-xxx`——可能只说"我想加个权限校验"、"这个地方有 bug"、"介绍下 codestable"，甚至只发一个 `cs`。本技能负责接住开放式输入，弄清意图，路由到对的子技能。 +`cs` 是轻量分诊入口，只把开放式诉求路由到推荐主入口。它不写 spec、不改 `.codestable/` 产物、不替下游流程执行阶段。 -**两件事，仅此两件**： - -1. 用户带具体诉求 → 匹配场景路由表，告诉用户该触发哪个 `cs-*`，并简单说明为什么 -2. 用户想了解体系 / 说不清想做什么 → 给精简体系速读 + 让用户挑或描述更具体的诉求 - -**本技能不做事**：不写 spec / 不读写 `.codestable/` 下内容产物 / 不替子技能跑流程。产出只有"建议触发哪个子技能"。 +旧阶段技能长期保留为兼容入口，但 `cs` 的主路径不再路由到它们。 --- ## 收到调用先做的扫描 -回应前每次都做（几个 tool 调用就够）： +回应前每次都做： -1. **看仓库有没有接入 CodeStable**——`Glob .codestable/` 看顶层目录 -2. **存在**——必须先 `Read .codestable/attention.md`（如果缺失提示骨架不完整，先补齐或重跑 `cs-onboard`）；再 `Read .codestable/reference/system-overview.md`（如果有）；`Glob` 一下 `features/` `issues/` `roadmap/` 看进行中的工作（拿目录名就够，不逐份读） -3. **不存在**——后面提示用户先走 `cs-onboard` -4. **看用户原话**——开放式还是带具体诉求？带诉求匹配路由表，没诉求给体系介绍 - -扫完才回应。让用户感觉你心里有数。 +1. 看仓库有没有 `.codestable/`。 +2. 已接入：读 `.codestable/attention.md`；若有 `.codestable/reference/system-overview.md` 也读；扫描进行中的 `features/`、`issues/`、`roadmap/`、`refactors/`。 +3. 未接入：提示先走 `cs-onboard`。 +4. 看本次调用参数（$ARGUMENTS）：非空且不是字面 `$ARGUMENTS` 时，作为用户诉求匹配路由表。 +5. 参数为空再看用户原话：开放式还是带具体诉求；带诉求匹配路由表，没诉求给体系速读。 --- -## 体系一图速读（用户没具体诉求 / 让你介绍时讲这个） +## 体系速读 -CodeStable 把开发活动建模成 **8 个实体 + 4 个流程**，所有产物聚在 `.codestable/`： +CodeStable 编排的是软件生命周期，不是 agent 团队。主要实体都落在 `.codestable/`： -``` +```text .codestable/ -├── requirements/ 需求 + 领域模型（VISION + capability + CONTEXT.md + adrs/） -├── roadmap/ 规划层（roadmap / roadmap-review / goal 执行包） -├── goals/ 目标实体（限定起点/终点，自主迭代 + Task agent 功能验收） -├── features/ 新增能力 spec 聚合根（design / design-review / impl / review / qa / accept） -├── issues/ 修 bug spec 聚合根（report / analyze / fix） -├── refactors/ 重构 spec 聚合根（beta） -├── audits/ 审计实体（主动扫描发现清单，不定修） -└── compound/ 知识沉淀（cs-keep 写自由 markdown，grep 检索） +├── requirements/ 需求 + 领域模型 +├── roadmap/ epic 的内部规划/goal 存储模型 +├── goals/ 目标实体 +├── features/ feature 生命周期产物 +├── issues/ issue 生命周期产物 +├── refactors/ refactor 生命周期产物 +├── audits/ 审计发现 +└── compound/ 知识沉淀 ``` -**四条流程**： +生命周期主流程入口： -- **新增能力**：`cs-feat-design` → `cs-feat-design-review` → `cs-feat-impl` → `cs-code-review` → `cs-feat-qa` → `cs-feat-accept`（想法模糊先 `cs-brainstorm` 分诊） -- **目标达成**：`cs-goal`（限定起点/终点 → interview/grill 写起点报告 → 自主实现/验证/迭代 → 完成前 Task agent 功能验收） -- **修 bug**：`cs-issue-report` → `cs-issue-analyze` → `cs-issue-fix` -- **重构**（beta）：`cs-refactor` / `cs-refactor-ff` +- `cs-feat`：feature 端到端，内部推进 design、design-review、impl、code review、QA、accept。 +- `cs-issue`：issue 端到端，内部推进 report、analyze、fix、code review。 +- `cs-refactor`：行为等价重构，内部选择标准模式或 fastforward mode。 +- `cs-epic`：大需求端到端，用户叫 epic，内部暂用 roadmap 存储模型。 +- `cs-docs`：对外文档写作，覆盖 tutorial / API reference。 +- `cs-docs-neat`：阶段收尾、文档同步、agent 入口和记忆整理。 +- `cs-code-review`：横切实现审查 gate。 -**横切**：commit 前走 `cs-code-review` 独立评审；流程跑完发现"值得记下来" → `cs-keep` 沉淀到 `compound/`（纯 markdown，grep 检索）。 - -**核心理念**：编排的是软件本身的生命周期（需求、领域模型、特性、bug、决策），不是 Agent。人在环——程序员对整体把控负责，AI 是高效执行体。 - -> 项目已 onboard 的话更详细总览看 `.codestable/reference/system-overview.md`。 +接入、goal、brainstorm、审计、需求、领域和知识沉淀等入口也可由 `cs` 路由；完整集合见下方场景路由表。 --- ## 场景路由表 -匹配用户的话到表里某行，告诉用户："你这个诉求建议走 `cs-xxx`，因为 {一句话理由}"。 - -### Route Governance - -`cs` 必须保持轻量只做路由，但每次路由都说明 governance 边界。默认输出短 route brief： +匹配用户诉求后输出 route brief： ```text -Route: {目标 skill 或阶段} +Route: {目标主入口} Context: {L0-L4} Reason: {为什么这条路由合适} Not routing to: {排除的相邻流程，如有歧义} Escalation: {什么情况会抬升 context level} -Next: {用户该触发什么，或这条路由会决定什么} +Next: {用户该触发什么，或本入口会决定什么} ``` -Context level 只说明轻重，`cs` 阶段不生成重型产物： - -- L0：纯状态 / 验证 / 同步。 -- L1：本地、可逆、不改变长期 intent。 -- L2：需要 owner 选择、授权、接受、延期或 sign off。 -- L3：会改变长期 spec、future agent 输入、capability boundary 或公开契约。 -- L4：旧 spec 漂移、冲突、source-of-truth 不清，需要 inventory / rehabilitation。 - -L2/L3 需 owner 审批/选择/授权/接受风险时，子流程先按 `.codestable/reference/approval-conventions.md` 在对应 unit 写 `approval-report.md`（design / issue analysis / acceptance 等阶段报告已承载审批上下文则免）。`cs` 自身通常只路由；唯一例外：route choice 本身需 owner 选择且无明确 unit 时，当 intake decision 写 `.codestable/brainstorms/{slug}/approval-report.md` 再 owner-stop，不要只给 chat-only brief。 - -升级触发器：需 owner 判断方向/授权/接受风险/finish-merge readiness；可能改长期 requirement / architecture / roadmap / decision / guide / skill；fast path 发现 capability boundary / public contract / future-agent instruction / spec drift；旧文档冲突或不确定哪个 canonical。路由不确定就按上面规则停下让用户选，不硬猜。 - | 用户说什么 / 想做什么 | 路由到 | |---|---| -| 仓库还没有 `.codestable/` | **先 `cs-onboard`**——所有其他 cs-* 都依赖这个目录 | -| 限定起点和终点 / 明确验收结果 / "帮我达成这个 goal" / "自主迭代直到完成" / "grill me 后开干" | `cs-goal`（起点 / iteration 报告；实现由 AI 自主推进；完成前 Task agent 功能验收） | -| 想法还模糊 / "有想法没想清楚" / "先聊聊" / "不知道是不是新功能" | `cs-brainstorm`（分诊后路由到 design / feature-brainstorm 落盘 / roadmap） | -| 新功能 / "加个 X" / "实现 XX" | `cs-feat`（路由 design / ff / impl / accept） | -| BUG / 异常 / 报错 / "这里不对" / "文档错了" | `cs-issue`（路由 report / analyze / fix） | -| 代码优化 / 重构 / 重写（行为不变） | `cs-refactor` / `cs-refactor-ff` | -| 审查系统 / 扫描 bug / 审计代码 / "有哪些问题" / "哪里可以优化" | `cs-audit`（主动扫描发现，只列清单不定修） | +| 仓库还没有 `.codestable/` | `cs-onboard` | +| 限定起点和终点 / 自主迭代直到完成 / goal | `cs-goal` | +| 想法模糊 / 先聊聊 / 不知道是不是新功能 | `cs-brainstorm` | +| 新功能 / 加个 X / 实现 XX / feature 中间问下一步 | `cs-feat` | +| BUG / 异常 / 报错 / 文档错了 / issue 中间问下一步 | `cs-issue` | +| 代码优化 / 重构 / 拆分 / 性能，且行为不变 | `cs-refactor` | +| 审查系统 / 扫描 bug / 审计代码 / 哪里可以优化 | `cs-audit` | | 补 / 更新需求文档 | `cs-req` | -| 拍板技术决策 / 加领域术语 / 项目要分子系统 | `cs-domain` | -| 大需求拆解 / "我想要一个 X 系统" / 排期规划 / 模块拆分 + 接口契约 | `cs-roadmap` | -| roadmap 人工确认前的规划审查 / "review 这个 roadmap" | `cs-roadmap-review` | -| 推进已有 roadmap / 执行整个 roadmap / "继续 roadmap" / "用 goal 稳步推进 roadmap" | `cs-roadmap-impl-goal` | -| feature design 人工确认前的方案审查 / "review 这个 design" | `cs-feat-design-review` | -| 合并前审一下 / "code review" / "代码评审" / 准备 PR / merge | `cs-code-review`（对当前 diff 做独立评审，质量门禁） | -| 术语 / 领域模型 / 架构决策 (ADR) / "这块属于哪个 context" | `cs-domain` | -| 摸代码调研 / 踩坑回顾 / 技术选型 / 长期约束 / 编码规约 / 可复用模式 / 库用法 / "值得记下来" | `cs-keep` | -| 一两行的项目注意事项 / 编译特殊设置 / 命令陷阱 / "记到 attention.md" | `cs-note` | -| 开发者指南 / 用户指南 | `cs-doc-tutorial` | -| 库 API 参考 | `cs-doc-api` | -| 阶段收尾 / 整理文档 / 同步 `CLAUDE.md` 或 `AGENTS.md` / 新人交接 | `cs-docs-neat` | -| 用户在 feature / issue 流程中间问"下一步" | 路由到对应入口（`cs-feat` / `cs-issue`），让该入口判断当前阶段 | +| 拍板技术决策 / 加领域术语 / 分 context | `cs-domain` | +| 大需求拆解 / 一个系统 / epic / roadmap / 执行整个 roadmap | `cs-epic` | +| 合并前审一下 / code review / 准备 PR / merge | `cs-code-review` | +| 值得记下来 / 踩坑 / 技巧 / 决策 / 调研 | `cs-keep` | +| 一两行项目注意事项 / 命令陷阱 / 记到 attention.md | `cs-note` | +| 开发者指南 / 用户指南 / API 参考 | `cs-docs` | +| 阶段收尾 / 整理文档 / 同步 README、CLAUDE.md、AGENTS.md 或记忆 | `cs-docs-neat` | -**判不出来 / 太抽象**："听起来像 {猜测}，但你描述里 {缺什么}。是 {选项 A} 还是 {选项 B}？" 让用户选不要硬猜。 +判不出来时问用户选项，不硬猜。 -### Route Level Quick Reference +--- + +## Route Level Quick Reference | Route | Default context | Escalate when | |---|---|---| | `cs-onboard` | L2/L4 | 旧文档需要 inventory、迁移或 trusted/stale 分类 | -| `cs-goal` | L1/L2 | 缺验收/起点状态需 grill + 起点报告；完成需 Task agent 功能验收；spec/公开契约变更或反复 blocker → owner-stop | +| `cs-goal` | L1/L2 | 缺验收/起点状态需 grill；完成需 Task agent 功能验收 | | `cs-brainstorm` | L1→L2 | owner 接受某方向或要下一步可执行项 | -| `cs-roadmap` / `cs-roadmap-review` / `cs-roadmap-impl-goal` | L2/L3 | roadmap 牵涉 spec 变更、capability boundary 或 requirement delta | -| `cs-feat` | L1 | 阶段不明或用户须选 design / ff / impl / accept | -| `cs-feat-design` / `cs-feat-design-review` | L2/L3 | design 触达长期 spec 或 future agent 输入 | -| `cs-feat-impl` | L0/L3 | 实现偏离已确认 design/checklist/spec | -| `cs-code-review` / `cs-feat-qa` | L1/L3 | 评审/验证发现行为偏差、契约或 spec 影响 | -| `cs-feat-accept` | L3 | 验收写入或校验长期 architecture / requirement / roadmap / finish readiness | -| `cs-feat-ff` | L1/L3 | 快速通道发现 capability-boundary、public contract 或 spec 影响 | -| `cs-issue` / `cs-issue-report` | L1 | 路由不清或复现/影响需 owner 确认 | -| `cs-issue-analyze` | L2 | owner 须选修复方案或接受风险 | -| `cs-issue-fix` | L0/L3 | 修复暴露错误 spec、capability boundary 或公开行为变更 | -| `cs-refactor` / `cs-refactor-ff` | L1/L2 | 跨模块、有风险或行为边界不确定 | -| `cs-code-review` | L1/L3 | review 发现 Critical/Important 或触达长期 spec / 公开契约 | -| `cs-req` | L3 | 总是：需求工作改变 future agent 的 source-of-truth | -| `cs-domain` | L1/L3 | 出现 code/doc/intent 冲突 | -| `cs-audit` | L1/L2 | owner 须裁定修 / 延 / 忽略 | -| `cs-keep` | L1/L3 | 沉淀升级为决策 / 规则 / spec 变更或长期约束 | -| `cs-note` | L1/L2 | 经验升级为常驻指令 | -| `cs-doc-tutorial` / `cs-doc-api` / `cs-docs-neat` | L1/L2 | 文档改变 user-facing 契约或公开理解 | -| `codestable-maintainer` | L2/L3 | 改 CodeStable 自身技能/harness/installed copy | +| `cs-epic` | L2/L3 | 牵涉 spec、capability boundary、requirement delta 或 goal 包 | +| `cs-feat` | L1/L3 | 阶段不明、design 触达长期 spec、实现偏离已确认设计 | +| `cs-issue` | L1/L3 | 复现/影响需 owner 确认，或修复暴露错误 spec/公开行为变化 | +| `cs-refactor` | L1/L2 | 跨模块、有风险或行为边界不确定 | +| `cs-code-review` | L1/L3 | review 发现 Critical/Important 或触达公开契约 | +| `cs-docs` | L1/L2 | 文档改变 user-facing 契约或公开理解 | +| `cs-docs-neat` | L1/L4 | 文档/记忆冲突、source-of-truth 不清、入口规则漂移 | +| `cs-keep` / `cs-note` | L1/L3 | 会影响 future agent 输入或长期约束 | + +L2/L3 需要 owner 审批、选择、授权或接受风险时，下游流程按 `.codestable/reference/approval-conventions.md` 写对应 approval 报告；`cs` 自身通常只路由。 --- -## 几种需要特别留心的情况 +## 兼容入口说明 -### 仓库还没接入 +以下旧技能名仍可直接使用，但只转入主入口： -任何 cs-* 流程但 `.codestable/` 不存在 → 说明这一点建议**先 `cs-onboard`**。不要直接路由到 cs-feat / cs-issue——它们的 SKILL.md 都假设 `.codestable/` 已存在。 +- Feature：`cs-feat-design`、`cs-feat-design-review`、`cs-feat-impl`、`cs-feat-qa`、`cs-feat-accept`、`cs-feat-ff` +- Issue：`cs-issue-report`、`cs-issue-analyze`、`cs-issue-fix` +- Refactor：`cs-refactor-ff` +- Docs：`cs-doc-tutorial`、`cs-doc-api` +- Epic：`cs-roadmap`、`cs-roadmap-review`、`cs-roadmap-impl-goal` -### 大需求被误当成 feature - -"我想要一个权限系统 / 通知中心 / SSO 接入"这类**一眼看出做不完一个 feature** 的诉求 → 不路由到 `cs-feat`，路由到 `cs-brainstorm`（大概率判 case 3 → `cs-roadmap`）或直接 `cs-roadmap`。理由：直接起 feature 会变成巨型 design 塞不下。 - -### "改一下 X" 但 X 是已有功能 - -先问这是 **bug 修复**（X 现在表现错了）还是 **需求变更**（X 现在表现没错，但策略变了）： - -- bug → `cs-issue` -- 需求变更 → `cs-req` 改需求 doc + 之后 `cs-feat` 跑实现 - -### 进行中的工作 - -扫描看到 `features/` 或 `issues/` 下已有相关目录 → 提一句"看到 `features/2026-04-22-xxx/` 已经存在，是接着做这个吗？" 让用户确认续作还是开新的。 - -### 沉淀类两个入口 - -- 写到 `.codestable/compound/` 一份独立 markdown（坑点 / 技巧 / 决策 / 调研，靠 grep 检索）→ `cs-keep` -- 一两行常驻提示"CodeStable 技能每次启动都得知道 X"（写到 `.codestable/attention.md`）→ `cs-note` - -判不出问用户："这个是要写一份独立文档（cs-keep），还是一两行启动必读（cs-note）？" - ---- - -## 介绍模式（用户只说想了解 / 不知道做什么） - -按这个顺序讲，**不一次倒出全部**： - -1. 一句话：CodeStable 是面向严肃工程的 AI 编码工作流，编排软件生命周期而不是 Agent -2. 9 实体 + 4 流程的速读图 -3. 问用户"你现在最想从哪儿开始？"，给三个引子： - - "我有个新功能想做" → cs-feat - - "代码里有个 bug" → cs-issue - - "项目还没接入 CodeStable" → cs-onboard - -收住，别把所有子技能细节讲一遍。用户问到具体的再展开。 - ---- - -## 退出 - -本技能没有"落盘"。退出条件一条： - -- [ ] 已告诉用户下一步触发哪个具体的 `cs-*` 子技能（或确认用户只是来了解，没要做事） - -输出形如： - -> 你这个诉求建议走 **`cs-xxx`**——{一句话理由}。 -> 触发后它会 {简述会发生什么：会先扫已有 spec / 会让你先描述 / 会进入分诊 / ...}。 -> 现在切到 `cs-xxx` 吗？ - ---- - -## 不做的事 - -- **不读写 `.codestable/` 下的内容产物**——这些是子技能的事 -- **不替子技能做决策**——不在本技能做 brainstorm 分诊，不替 cs-domain 判断要不要写 ADR -- **不一次推荐多个技能**——每次只指一条路；两个独立诉求分两轮 -- **不重复体系总览细节**——`.codestable/reference/system-overview.md` 才是权威完整版 -- **不绕过 `cs-onboard`**——仓库没接入就先 onboard +新文档和新提示词应使用主入口。 diff --git a/tests/test_codestable_worktree_gate.py b/tests/test_codestable_worktree_gate.py index 7c03654..8fa2c12 100644 --- a/tests/test_codestable_worktree_gate.py +++ b/tests/test_codestable_worktree_gate.py @@ -251,14 +251,14 @@ def test_quarantine_refuses_untracked_secret_like_files(tmp_path: Path) -> None: def test_runtime_tool_paths_are_documented() -> None: root = Path(__file__).resolve().parents[1] - tools_doc = (root / "plugins/codestable/skills/cs-onboard/reference/tools.md").read_text(encoding="utf-8") - tools_doc += "\n" + (root / "plugins/codestable/skills/cs-onboard/reference/tools-context.md").read_text(encoding="utf-8") + tools_doc = (root / "plugins/codestable/skills/cs-onboard/references/tools.md").read_text(encoding="utf-8") + tools_doc += "\n" + (root / "plugins/codestable/skills/cs-onboard/references/tools-context.md").read_text(encoding="utf-8") assert "python3 .codestable/tools/codestable-doctor.py --root . --json" in tools_doc assert "python3 .codestable/tools/codestable-worktree-gate.py --root . --json start" in tools_doc assert "python3 .codestable/tools/codestable-finish-worktree.py --root ." in tools_doc assert "python3 .codestable/tools/codestable-worktree-inbox.py --root . --json" in tools_doc - hook_doc = (Path(__file__).resolve().parents[1] / "plugins/codestable/skills/cs-onboard/reference/branch-guard-hooks.md").read_text( + hook_doc = (Path(__file__).resolve().parents[1] / "plugins/codestable/skills/cs-onboard/references/branch-guard-hooks.md").read_text( encoding="utf-8" ) assert "codestable-ai-branch-guard.py" in hook_doc diff --git a/tests/test_plugin_package.py b/tests/test_plugin_package.py index 0c76567..ce8dbad 100644 --- a/tests/test_plugin_package.py +++ b/tests/test_plugin_package.py @@ -42,8 +42,7 @@ def make_repo(tmp_path: Path) -> Path: "/dist/\n" "__pycache__\n" "*.pyc\n" - ".DS_Store\n" - ".codestable/\n", + ".DS_Store\n", encoding="utf-8", ) write_json( @@ -224,6 +223,37 @@ def test_root_standalone_skill_residue_fails(tmp_path: Path) -> None: assert any("root standalone skill entry" in message for message in messages(findings)) +def test_skill_reference_spelling_conflict_fails(tmp_path: Path) -> None: + repo = make_repo(tmp_path) + skill_dir = repo / "plugins/codestable/skills/cs-feat" + (skill_dir / "reference").mkdir() + (skill_dir / "references").mkdir() + + findings = checker.check_repo(repo) + + assert any("must not contain both reference/ and references/" in message for message in messages(findings)) + + +def test_skill_reference_directory_spelling_fails(tmp_path: Path) -> None: + repo = make_repo(tmp_path) + skill_dir = repo / "plugins/codestable/skills/cs-feat" + (skill_dir / "reference").mkdir() + + findings = checker.check_repo(repo) + + assert any("must use references/, not reference/" in message for message in messages(findings)) + + +def test_nested_references_directory_fails(tmp_path: Path) -> None: + repo = make_repo(tmp_path) + nested = repo / "plugins/codestable/skills/cs-feat/references/design/references" + nested.mkdir(parents=True) + + findings = checker.check_repo(repo) + + assert any("nested references/ directories are not allowed" in message for message in messages(findings)) + + def test_non_cs_skill_and_generated_artifacts_fail(tmp_path: Path) -> None: repo = make_repo(tmp_path) extra_skill = repo / "plugins/codestable/skills/other-skill" @@ -252,6 +282,15 @@ def test_ignored_install_asset_fails(tmp_path: Path) -> None: assert any("install asset is ignored" in message for message in messages(findings)) +def test_ignored_codestable_fails(tmp_path: Path) -> None: + repo = make_repo(tmp_path) + (repo / ".gitignore").write_text(".codestable/\n", encoding="utf-8") + + findings = checker.check_repo(repo) + + assert ".codestable must not be ignored" in messages(findings) + + def test_readme_commands_stay_current(tmp_path: Path) -> None: repo = make_repo(tmp_path) (repo / "README.md").write_text("codex plugin install codestable\n", encoding="utf-8") diff --git a/tests/test_skill_entry_simplification.py b/tests/test_skill_entry_simplification.py new file mode 100644 index 0000000..c57d8ff --- /dev/null +++ b/tests/test_skill_entry_simplification.py @@ -0,0 +1,297 @@ +from __future__ import annotations + +import importlib.util +import re +import sys +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +SKILLS = ROOT / "plugins/codestable/skills" + +COMPATIBILITY_ENTRIES = { + "cs-feat-design": ("cs-feat", "requested_stage", "design"), + "cs-feat-design-review": ("cs-feat", "requested_stage", "design-review"), + "cs-feat-impl": ("cs-feat", "requested_stage", "implementation"), + "cs-feat-qa": ("cs-feat", "requested_stage", "qa"), + "cs-feat-accept": ("cs-feat", "requested_stage", "acceptance"), + "cs-feat-ff": ("cs-feat", "requested_mode", "fastforward"), + "cs-issue-report": ("cs-issue", "requested_stage", "report"), + "cs-issue-analyze": ("cs-issue", "requested_stage", "analyze"), + "cs-issue-fix": ("cs-issue", "requested_stage", "fix"), + "cs-refactor-ff": ("cs-refactor", "requested_mode", "fastforward"), + "cs-doc-tutorial": ("cs-docs", "requested_mode", "tutorial"), + "cs-doc-api": ("cs-docs", "requested_mode", "api"), + "cs-roadmap": ("cs-epic", "requested_stage", "planning"), + "cs-roadmap-review": ("cs-epic", "requested_stage", "review"), + "cs-roadmap-impl-goal": ("cs-epic", "requested_stage", "goal-package"), +} + +MAIN_REFERENCE_PATHS = [ + "cs-feat/references/design/protocol.md", + "cs-feat/references/design-review/protocol.md", + "cs-feat/references/implementation/protocol.md", + "cs-feat/references/qa/protocol.md", + "cs-feat/references/acceptance/protocol.md", + "cs-feat/references/fastforward/protocol.md", + "cs-issue/references/report/protocol.md", + "cs-issue/references/analyze/protocol.md", + "cs-issue/references/fix/protocol.md", + "cs-refactor/references/standard/protocol.md", + "cs-refactor/references/fastforward/protocol.md", + "cs-docs/references/tutorial/protocol.md", + "cs-docs/references/api/protocol.md", + "cs-epic/references/planning/protocol.md", + "cs-epic/references/review/protocol.md", + "cs-epic/references/goal/protocol.md", + "cs-code-review/references/independent-review/protocol.md", +] + +REFACTOR_LIBRARY_PATHS = [ + "cs-refactor/references/library/methods.md", + "cs-refactor/references/library/methods-l4.md", + "cs-refactor/references/library/methods-architecture.md", + "cs-refactor/references/library/refusal-routing.md", + "cs-refactor/references/library/scan-checklist-format.md", +] + +REFERENCE_MIGRATION_MARKERS = [ + "不是独立 skill 入口", + "SKILL.md 只保留", + "按 `SKILL.md` 所在目录", + "同包 `reference.md`", + "## 启动必读", +] + +LEGACY_STAGE_SKILL_NAMES = [ + "cs-feat-design", + "cs-feat-design-review", + "cs-feat-impl", + "cs-feat-qa", + "cs-feat-accept", + "cs-feat-ff", + "cs-issue-report", + "cs-issue-analyze", + "cs-issue-fix", + "cs-doc-tutorial", + "cs-doc-api", + "cs-roadmap", + "cs-roadmap-review", + "cs-roadmap-impl-goal", + "cs-refactor-ff", +] + +USER_ROUTING_GUIDANCE_PATHS = [ + "cs-brainstorm/SKILL.md", + "cs-brainstorm/reference.md", + "cs-req/SKILL.md", +] + +LEGACY_ROUTING_PHRASES = [ + "`cs-roadmap`", + "cs-roadmap", + "`cs-feat-design`", + "`cs-feat-impl`", + "`cs-feat-qa`", + "`cs-feat-accept`", + "`cs-doc-tutorial`", + "`cs-doc-api`", + "`cs-issue-report`", + "`cs-issue-analyze`", + "`cs-issue-fix`", + "`cs-refactor-ff`", +] + + +def load_codestable_common(): + module_path = SKILLS / "cs-onboard/tools/codestable_common.py" + spec = importlib.util.spec_from_file_location("codestable_common", module_path) + assert spec and spec.loader + module = importlib.util.module_from_spec(spec) + sys.modules[spec.name] = module + spec.loader.exec_module(module) + return module + + +def test_skill_markdown_files_stay_under_line_limit() -> None: + oversized = [] + for path in SKILLS.rglob("*.md"): + line_count = len(path.read_text(encoding="utf-8").splitlines()) + if line_count > 300: + oversized.append((path.relative_to(ROOT).as_posix(), line_count)) + + assert oversized == [] + + +def test_compatibility_entries_delegate_to_main_protocols() -> None: + for skill, (main, key, value) in COMPATIBILITY_ENTRIES.items(): + path = SKILLS / skill / "SKILL.md" + text = path.read_text(encoding="utf-8") + + assert "兼容入口" in text + assert (SKILLS / main / "SKILL.md").is_file(), main + assert f"按已安装 skill 名称加载 `{main}`" in text + assert "../" not in text + assert f"{key}: {value}" in text + assert "不维护独立流程规则" in text + assert len(text.splitlines()) <= 40 + + +MAIN_ENTRY_SKILLS = [ + "cs", + "cs-feat", + "cs-issue", + "cs-refactor", + "cs-docs", + "cs-epic", + "cs-code-review", + "cs-docs-neat", +] + + +def frontmatter_of(text: str) -> str: + return text.split("---", 2)[1] + + +def test_main_entries_declare_argument_hint_and_intent_fallback() -> None: + for skill in MAIN_ENTRY_SKILLS: + text = (SKILLS / skill / "SKILL.md").read_text(encoding="utf-8") + + assert "argument-hint:" in frontmatter_of(text), skill + assert "$ARGUMENTS" in text, skill + # 宿主不替换参数时必须优雅降级，不能把字面 $ARGUMENTS 当诉求。 + assert "字面 `$ARGUMENTS`" in text, skill + + +def test_compatibility_entries_do_not_declare_argument_hint() -> None: + for skill in COMPATIBILITY_ENTRIES: + text = (SKILLS / skill / "SKILL.md").read_text(encoding="utf-8") + + assert "argument-hint" not in text, skill + assert "$ARGUMENTS" not in text, skill + + +def test_main_entry_references_exist() -> None: + for rel_path in MAIN_REFERENCE_PATHS: + assert (SKILLS / rel_path).is_file(), rel_path + + +def test_protocol_references_are_not_shadow_skills() -> None: + for rel_path in MAIN_REFERENCE_PATHS: + path = SKILLS / rel_path + text = path.read_text(encoding="utf-8") + head = "\n".join(text.splitlines()[:5]) + + assert text.startswith("# "), rel_path + assert not text.startswith("---"), rel_path + assert "\nname:" not in head, rel_path + assert "\ndescription:" not in head, rel_path + assert "## 启动必读" not in text, rel_path + + +def test_references_do_not_keep_migration_markers() -> None: + offenders = [] + for path in (SKILLS).rglob("references/**/*.md"): + text = path.read_text(encoding="utf-8") + head = "\n".join(text.splitlines()[:5]) + if re.search(r"(?m)^name:", head): + offenders.append((path.relative_to(ROOT).as_posix(), "frontmatter name")) + for marker in REFERENCE_MIGRATION_MARKERS: + if marker in text: + offenders.append((path.relative_to(ROOT).as_posix(), marker)) + + assert offenders == [] + + +def test_references_prefer_main_entries_over_legacy_stage_skills() -> None: + offenders = [] + for path in (SKILLS).rglob("references/**/*.md"): + text = path.read_text(encoding="utf-8") + for legacy_name in LEGACY_STAGE_SKILL_NAMES: + if legacy_name in text: + offenders.append((path.relative_to(ROOT).as_posix(), legacy_name)) + + assert offenders == [] + + +def test_user_routing_guidance_prefers_main_entries() -> None: + offenders = [] + for rel_path in USER_ROUTING_GUIDANCE_PATHS: + path = SKILLS / rel_path + text = path.read_text(encoding="utf-8") + for phrase in LEGACY_ROUTING_PHRASES: + if phrase in text: + offenders.append((rel_path, phrase)) + + assert offenders == [] + + +def test_code_review_ad_hoc_git_range_uses_range_diff() -> None: + text = (SKILLS / "cs-code-review/SKILL.md").read_text(encoding="utf-8") + + assert "ad-hoc 参数如果是 git range" in text + assert "git diff {range}" in text + assert "ad-hoc range 审查允许工作区干净" in text + + +def test_no_directory_contains_both_reference_spellings() -> None: + conflicts = [] + for directory in [SKILLS, *[path for path in SKILLS.rglob("*") if path.is_dir()]]: + if not (directory / "reference").is_dir() or not (directory / "references").is_dir(): + continue + conflicts.append(directory.relative_to(ROOT).as_posix()) + + assert conflicts == [] + + +def test_skill_package_reference_directories_follow_agent_skills_convention() -> None: + invalid = [] + for directory in [path for path in SKILLS.rglob("*") if path.is_dir()]: + rel_parts = directory.relative_to(SKILLS).parts + if directory.name == "reference": + invalid.append(directory.relative_to(ROOT).as_posix()) + if directory.name == "references" and (len(rel_parts) != 2 or rel_parts[1] != "references"): + invalid.append(directory.relative_to(ROOT).as_posix()) + + assert invalid == [] + + +def test_main_entry_reference_pointers_resolve_to_files() -> None: + main_entries = [ + "cs-feat", + "cs-issue", + "cs-refactor", + "cs-docs", + "cs-epic", + "cs-code-review", + "cs-docs-neat", + ] + missing = [] + + for skill in main_entries: + skill_dir = SKILLS / skill + text = (skill_dir / "SKILL.md").read_text(encoding="utf-8") + for match in re.finditer(r"`(references/[^`]+?\.md)`", text): + rel_path = match.group(1) + if "*" in rel_path: + if not list(skill_dir.glob(rel_path)): + missing.append(f"{skill}/{rel_path}") + elif not (skill_dir / rel_path).is_file(): + missing.append(f"{skill}/{rel_path}") + + assert missing == [] + + +def test_refactor_library_references_are_migrated() -> None: + assert not (SKILLS / "cs-refactor/reference").exists() + for rel_path in REFACTOR_LIBRARY_PATHS: + assert (SKILLS / rel_path).is_file(), rel_path + + +def test_new_main_entries_are_registered() -> None: + common = load_codestable_common() + + assert "cs-docs" in common.KNOWN_SKILL_DIRS + assert "cs-epic" in common.KNOWN_SKILL_DIRS + for skill in COMPATIBILITY_ENTRIES: + assert skill in common.KNOWN_SKILL_DIRS diff --git a/tools/check-plugin-package.py b/tools/check-plugin-package.py index 7eacd92..8ff56d5 100644 --- a/tools/check-plugin-package.py +++ b/tools/check-plugin-package.py @@ -163,6 +163,23 @@ def check_skill_layout(root: Path, findings: list[Finding]) -> None: findings.append(Finding(path.name, "root standalone skill entry must be removed from this distribution branch")) +def check_reference_directory_spellings(root: Path, findings: list[Finding]) -> None: + skills_dir = root / "plugins/codestable/skills" + if not skills_dir.is_dir(): + return + + directories = [skills_dir, *[path for path in sorted(skills_dir.rglob("*")) if path.is_dir()]] + for directory in directories: + if (directory / "reference").is_dir() and (directory / "references").is_dir(): + findings.append(Finding(rel(directory, root), "must not contain both reference/ and references/")) + if directory.name == "reference": + findings.append(Finding(rel(directory, root), "skill package directory must use references/, not reference/")) + if directory.name == "references": + parts = directory.relative_to(skills_dir).parts + if len(parts) != 2 or parts[1] != "references": + findings.append(Finding(rel(directory, root), "nested references/ directories are not allowed; use support/")) + + def check_ignored_assets(root: Path, findings: list[Finding]) -> None: assets = [ root / ".agents/plugins/marketplace.json", @@ -178,6 +195,17 @@ def check_ignored_assets(root: Path, findings: list[Finding]) -> None: findings.append(Finding(rel(path, root), "install asset is ignored by .gitignore")) +def check_codestable_not_ignored(root: Path, findings: list[Finding]) -> None: + result = subprocess.run( + ["git", "check-ignore", "--no-index", "-q", "--", ".codestable/attention.md"], + cwd=root, + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + ) + if result.returncode == 0: + findings.append(Finding(".gitignore", ".codestable must not be ignored")) + + def check_generated_exclusions(root: Path, findings: list[Finding]) -> None: blocked = {".DS_Store", ".pytest_cache"} scan_roots = [root / "plugins/codestable"] @@ -230,7 +258,9 @@ def check_repo(root: Path) -> list[Finding]: check_manifest_versions(root, version, findings) check_catalog_contracts(root, findings) check_skill_layout(root, findings) + check_reference_directory_spellings(root, findings) check_ignored_assets(root, findings) + check_codestable_not_ignored(root, findings) check_generated_exclusions(root, findings) check_readme_commands(root, findings) return findings