Cabbage Skill: Project Documentation Lifecycle & Workflow Gates
1. When to Use & Scenario Dispatch (Phase 0)
Use this Skill whenever performing any software engineering, architecture, documentation, or operational activity.
Before beginning, classify the incoming task against the 10 scenario archetypes:
| Scenario Archetype |
Cabbage Change Type |
Workflow Path |
Key Actions & Exit Criteria |
| New Feature / Capability |
feature |
Full Lifecycle |
PRD -> Tech Spec (Testing Decisions) -> Tasks (Vertical Slices) -> Implementation -> Dual-Axis Review -> Merge |
| Bug / Regression |
bugfix |
Lightweight Corrective |
Reproduce -> Failing Test (RED) -> Minimal Fix (GREEN) -> Regression Verify |
| Production Incident / Hotfix |
hotfix / incident |
Fast-Track Patch |
Patch from release tag -> Minimal Fix -> Release PR -> Rollback plan |
| Business Adjustment |
feature / bugfix |
Change Management |
Impact analysis -> Backward compatibility check -> Update spec -> Implement |
| Refactoring |
refactor |
Behavior-Preserving |
Test safety net -> Stepwise refactor -> Differential/snapshot parity check |
| Tech Debt Cleanup |
refactor |
Behavior-Preserving Removal |
Inventory unused assets -> Verify consumer references -> Delete -> Full regression |
| Infrastructure Change |
integration / refactor |
CI-as-Acceptance |
Small incremental steps -> Push to CI -> Verify build pipeline & regression |
| Documentation Update |
feature or direct docs |
Docs-as-Code |
Update canonical docs -> Terminology check -> Docs build verify (cabbage docs build) |
| Rollback & Recovery |
hotfix |
Controlled Rollback |
Revert PR -> Create root-cause corrective change -> Clean worktrees |
| Technical Research |
architecture |
Evidence-Driven |
Frame hypothesis -> Conduct research/POC -> Document findings & trade-offs |
- Reference:
references/decision-tree.md for full classification tree and impact mappings.
2. Core Principles & Anti-Rot Rules
- Single Source of Truth: Every architectural or product fact lives in exactly one canonical document; all other docs link to it.
- Current-State vs. Decision History:
- Current-state docs (
docs/01-product/, docs/03-architecture/system-design/, docs/05-api/, docs/13-operations/) describe the system as it exists now and are updated in-place.
- Decision-history docs (
ADR, RFC, postmortem) are immutable historical records. Never rewrite history; explicitly supersede older decisions with new ones.
- Content Signatures & Cascading Invalidation: Verifying an artifact computes a cryptographic SHA-256 signature of its content, workflow schema, and upstream dependencies. Modifying an upstream artifact automatically invalidates downstream stages to
stale.
- Zero Placeholder & Strict Link Integrity: Verification rejects any residual
TODO, TBD, FIXME, or default scaffold prompts, as well as broken local relative links.
- Atomic PR Delivery: Code changes and their associated documentation changes must be committed and delivered in the same Pull Request.
- Automated Specification Synchronization: Running
cabbage sync or cabbage archive automatically extracts verified specifications into the persistent docs/ hierarchy.
- No Final-v2-Copy Anti-Patterns: Avoid filenames like
spec-v2-final.md. Maintain stable paths and let Git manage version history.
3. Comprehensive Reference Index & Navigation
Before or during execution, consult the following dedicated reference guides in references/:
| Reference Document |
Scope & Key Topics |
When to Consult |
references/cli.md |
Complete CLI syntax, subcommands, flags, exit codes, and JSON outputs |
Executing or debugging any cabbage command |
references/decision-tree.md |
10 scenario archetypes, classification tree, impact matrix, conditional activations |
Classifying a new task or configuring impact flags |
references/lifecycle.md |
Change states (active / archived), stage state machine, SHA-256 signatures, stale triggers |
Understanding state transitions or resolving gate blocks |
references/directory-structure.md |
Standard 22-category docs/ tree layout and placement rules |
Locating, creating, or moving long-lived documentation |
references/document-types.md |
Specifications, Testing Decisions, DAG vertical task slices, and lifecycle rules for 12 artifact types |
Writing PRD, Tech Spec, ADR, RFC, API Design, Task DAGs, etc. |
references/adoption.md |
7-phase flow for scanning, classifying, and migrating existing repository docs |
Onboarding pre-existing project documentation |
references/validation.md |
Automated validation rules, TDD protocol, and Dual-Axis Review framework |
Troubleshooting verify/validate or reviewing PRs |
references/linking-rules.md |
Relative path resolution, stable heading anchors, cross-referencing rules |
Writing Markdown links between files |
references/naming-conventions.md |
Kebab-case naming, ADR/RFC numbering formats (ADR-0001-...), anti-patterns |
Naming change workspaces, ADRs, RFCs, and files |
references/diagrams.md |
Mermaid diagram syntax templates (Flowchart, Sequence, State, ER, Class, Git) |
Creating or reviewing architectural diagrams |
references/documentation-site.md |
VitePress 1.6+ configuration, Mermaid integration, local dev preview, static build |
Previewing or compiling the docs/ site |
references/enforcement.md |
CI gate configuration, branch protection, CODEOWNERS, agent security boundary |
Setting up CI/CD pipelines or permission policies |
references/ownership.md |
Code-to-documentation parity, frontmatter metadata, team ownership boundaries |
Assigning doc maintainers and PR reviewers |
4. Standard Operating Procedures (SOPs)
SOP 1: Feature & Capability Delivery Flow
Follow this end-to-end workflow when implementing a new feature or business capability.
flowchart TD
Pre["0. Grill-Me Alignment (Context & Boundaries)"] --> A["1. cabbage doctor & new feature <id>"]
A --> B["2. cabbage impact <id> --set ..."]
B --> C["3. Draft PRD, Tech Spec (Options) & Task DAG (SOP)"]
C --> D["4. cabbage verify <id> <stage>"]
D --> E{"5. cabbage gate <id> implementation"}
E -- Blocked --> C
E -- Allowed --> F["6. cabbage tasks --export-dag & Parallel Subagent TDD"]
F --> G["7. Mark Tasks Done [x] & Verify test-plan/release-plan"]
G --> H["8. cabbage validate <id> & cabbage sync <id>"]
H --> I{"9. Dual-Axis Review & cabbage gate <id> merge"}
I -- Blocked --> F
I -- Allowed --> J["10. Merge PR & cabbage archive <id>"]
Step 0: Pre-Flight Context Alignment & Grill-Me Protocol
Before touching workflow files or generating artifacts, AI and human must establish a crystal-clear boundary consensus:
- Context & Codebase Exploration:
- Inspect existing codebase, canonical docs (
docs/), and recent changes first.
- Never ask questions that can be answered by reading the codebase.
- Grill-Me Deep Alignment:
- Probe the intent iteratively: clarify the fundamental problem, business value, user personas, and hard constraints.
- Explicitly define In Scope vs. Explicit Non-Goals to eliminate scope creep before it starts.
- Formulate questions concisely (using structured options / questionnaires where applicable).
- Asymmetric Decision Framework (Frontal-Lobe Protection):
- AI Autonomous Decisions: Micro-level technical details, private helper structures, internal naming, local refactorings, and test mocks are decided directly by AI without cognitive overhead for the human.
- Human Gate Decisions: Strategic trade-offs, public API contracts, database schema migrations, billing/security policies, and breaking changes must be presented with options and decided by the human.
- Anchor in PRD:
- Record the validated assumptions, boundaries, and decision tiers into
.cabbage/changes/<change-id>/prd.md under ## Grill-Me Alignment Summary and ## Decision Boundaries.
Step 1: Initialize Workspace & Environment Check
Check environment prerequisites and initialize the change workspace:
cabbage doctor
cabbage new feature <change-id>
- Reference:
references/naming-conventions.md for <change-id> naming.
Step 2: Impact Analysis & Stage Activation
Evaluate affected technical domains and activate conditional stages:
cabbage impact <change-id>
cabbage impact <change-id> --set api=true --set database=true --set security=true
- Reference:
references/decision-tree.md for impact field mappings.
Step 3: Author Artifacts, DAG Task Decomposition & Stage Verification
Inspect next ready stages, fill in the generated templates in .cabbage/changes/<change-id>/, remove all placeholders, and verify each stage:
cabbage next <change-id>
# Edit .cabbage/changes/<change-id>/prd.md (contains Grill-Me outcomes and Decision Boundaries)
cabbage verify <change-id> prd
# Edit tech-spec.md (must evaluate Architecture Options and include Testing Decisions)
cabbage verify <change-id> tech-spec
# Edit tasks.md (must define Mermaid DAG, Parallel Groups, and Task SOP per slice)
cabbage verify <change-id> tasks
- Architecture Options Protocol:
- In
tech-spec.md, formulate 2 to 3 distinct architectural options (e.g. Minimal Low-Risk, Scalable Decoupled, Ideal Long-Term).
- Compare benefits, costs, and risks explicitly before committing to the design.
- Task DAG & Standard Operating Procedure (SOP):
- Model tasks as a Directed Acyclic Graph (DAG) with Mermaid
flowchart TD.
- Slice tasks vertically (end-to-end observable behavior), avoiding horizontal tech layers.
- Declare explicit
Blocked By dependencies (true blocking only; no circular dependencies).
- Every Task block must define its 4-step SOP:
- [RED] Test Seam: Define public test seam and write failing test.
- [GREEN] Implement: Minimal code to pass tests.
- [REFACTOR] Clean: Refactor, lint, type check, preserve behavior.
- [VERIFY] Validate: Run targeted verification command.
- Reference:
references/document-types.md for Testing Decisions, Architecture Options, and DAG Task SOP standards.
- Reference:
references/diagrams.md for Mermaid architectural and DAG diagram templates.
Step 4: Pre-Implementation Gate Guard
Before writing source code, confirm the implementation gate passes:
cabbage gate <change-id> implementation
If this command exits with non-zero or outputs BLOCKED, resolve missing or stale stages before touching code.
Step 5: TDD Implementation & Subagent Parallel Orchestration
Execute tasks according to the DAG topological order:
- DAG Inspection & Dispatch Export:
- Standard Operating Procedure (Task SOP):
- Each worker or subagent executes the 4-step SOP strictly against the designated test seam and verification command.
- Mark task items
- [ ] to - [x] as slices are verified.
- Topological Progression:
- Independent DAG branches run in parallel; convergence nodes run only after all prerequisites are marked green.
- Reference:
references/validation.md for TDD behavioral protocol and Dual-Axis Review.
Step 6: Post-Implementation Verification & Plans
Complete and verify test-plan.md and release-plan.md:
cabbage verify <change-id> tasks
cabbage verify <change-id> test-plan
cabbage verify <change-id> release-plan
Step 7: Full Validation & Specification Sync
Validate all change constraints and synchronize specifications into docs/:
cabbage validate <change-id>
cabbage sync <change-id>
cabbage docs build
- Reference:
references/directory-structure.md for synced target paths.
- Reference:
references/documentation-site.md for VitePress build details.
Step 8: Dual-Axis Review & Merge Gate
Execute Dual-Axis Review (Specification Axis + Convention Axis) and evaluate merge readiness:
cabbage gate <change-id> merge
cabbage ci --base origin/main
- Reference:
references/validation.md for Dual-Axis Review criteria.
Step 9: PR Merge & Archival
After merging the PR into the target branch:
cabbage archive <change-id>
- Reference:
references/lifecycle.md for archival mechanics.
SOP 2: Existing Project Documentation Adoption Flow
Follow this procedure when onboarding an existing repository with pre-existing documentation.
# 1. Scaffold Cabbage base without touching existing docs
cabbage init
# 2. Inventory all existing markdown documentation
cabbage adopt
# 3. Apply suggested migrations or manually resolve review rows
cabbage adopt --apply
# 4. Create adoption baseline change record
cabbage new feature adopt-existing-docs
# 5. Verify links and site build
cabbage validate adopt-existing-docs
cabbage docs build
# 6. Merge baseline PR and enable CI enforcement
- Reference:
references/adoption.md for the detailed 7-phase adoption guide.
- Reference:
references/enforcement.md for branch protection and CI setup.
SOP 3: Architecture Change & ADR/RFC Decision Flow
Follow this procedure when introducing systemic architectural changes, new design patterns, or major dependencies.
- Create Architecture Workspace:
cabbage new architecture <change-id>
- Draft Decision Records & Proposals:
- Write
adr.md following standard Context-Decision-Consequences format.
- If broad cross-team discussion is required, draft
rfc.md.
- Embed Mermaid topology and sequence diagrams directly in the text.
- Verify Decision Artifacts:
cabbage verify <change-id> adr
cabbage verify <change-id> tech-spec
cabbage gate <change-id> implementation
- Sync to Persistent Architecture Tree:
cabbage sync <change-id>
This automatically registers ADR-XXXX under docs/03-architecture/adr/.
- Reference:
references/document-types.md and references/naming-conventions.md.
SOP 4: Bugfix & Hotfix Flow
Follow this streamlined procedure for defect corrections.
- Create Bugfix / Hotfix Workspace:
cabbage new bugfix <change-id>
# or for urgent production defects:
cabbage new hotfix <change-id>
- Minimal Impact Assessment:
cabbage impact <change-id>
Only enable fields directly affected by the bugfix (e.g. testing=true).
- Reproduce & Fix with TDD:
- Write a failing reproduction test (RED).
- Apply minimal fix (GREEN).
- Document root cause analysis in
tasks.md and mark checklist items - [x].
- Verify & Merge:
cabbage verify <change-id> tasks
cabbage gate <change-id> merge
SOP 5: Database & Data Migration Flow
Follow this procedure when adding or modifying database schemas, tables, indexes, or running data backfills.
- Create Migration Workspace & Set Impact:
cabbage new migration <change-id>
cabbage impact <change-id> --set database=true --set deployment=true
- Author Database Design Artifact (
database-design.md):
- Define exact DDL / schema modifications.
- Document forward migration steps and rollback procedures.
- Include ER diagrams using Mermaid syntax.
- Evaluate locking, zero-downtime constraints, and data safety.
- Verify & Execute Gate:
cabbage verify <change-id> database-design
cabbage verify <change-id> tasks
cabbage gate <change-id> implementation
- Sync & Merge:
cabbage sync <change-id>
cabbage gate <change-id> merge
SOP 6: Production Incident & Postmortem Flow
Follow this procedure to document live service outages, root cause analysis, and preventative actions.
- Create Incident Workspace:
cabbage new incident <incident-id>
- Document Incident Timeline & Postmortem:
- Record exact UTC timeline in
incident.md.
- Conduct 5-Why root cause analysis in
postmortem.md.
- List actionable preventative tasks with assigned owners.
- Verify & Archive into Incident History:
cabbage verify <incident-id> incident
cabbage verify <incident-id> postmortem
cabbage sync <incident-id>
cabbage archive <incident-id>
Archived records permanently reside in docs/15-incidents/.
5. Long-Session Context Management & Handoff
During extended execution or when switching between major phases:
- Context Pressure Mitigation: When conversation history grows large or when pausing work:
- Produce a concise handoff record under
docs/dev/handoff-<YYYY-MM-DD>.md summarizing:
- Current change ID and phase.
- Completed stages and verified artifacts.
- Active tasks in progress and immediate next step.
- Key files created/modified.
- Session Resumption:
- Check existing changes:
cabbage status
- Inspect ready actions:
cabbage next <change-id>
- Resume directly from the next unblocked stage rather than re-scanning the entire project.
6. Command Quick Reference
# Environment & Diagnosis
cabbage doctor # Diagnostic check
cabbage init # Greenfield init
cabbage adopt [--apply] # Adopt existing docs
# Workspace & Stages
cabbage new <type> <change-id> # Create change workspace
cabbage status [change-id] # View stage progress
cabbage next <change-id> # View ready/blocked stages
cabbage impact <change-id> [--set k=v] # Inspect or update impact matrix
cabbage discard <change-id> # Remove active change
# Verification & Gates
cabbage verify <change-id> <stage> # Verify single artifact
cabbage validate [<change-id> | --all] # Validate markdown & links
cabbage gate <change-id> implementation|merge # Evaluate lifecycle gate
# Sync, Archive & CI
cabbage sync <change-id> # Extract specs into docs/
cabbage archive <change-id> # Archive completed change
cabbage ci --base <git-ref> # CI diff & gate runner
# Documentation Site
cabbage docs install|dev|build # VitePress lifecycle
- Reference:
references/cli.md for full parameter specifications and exit codes.
7. Troubleshooting & Common Failure Modes
| Error / Failure |
Root Cause |
Resolution |
verify: contains placeholder: ... |
File contains TODO, TBD, FIXME, or default template prompt text |
Replace placeholder text with real content. |
verify: unchecked tasks remain |
tasks.md contains - [ ] unchecked checklist items |
Mark completed items as - [x] after implementation. |
gate implementation: BLOCKED |
Required pre-implementation artifacts are unverified (pending) or stale |
Run cabbage next <id> and verify unready stages with cabbage verify. |
stage status: stale |
Upstream artifact, workflow definition, or impact flag was modified |
Review the artifact against updated upstream dependencies, then re-run cabbage verify <id> <stage>. |
validate: broken link ... |
A relative link in Markdown references a nonexistent file or anchor |
Check relative path depth or update heading anchor slug. See references/linking-rules.md. |
docs build: failed |
VitePress dead link check or unclosed code fence |
Run cabbage validate --all to pinpoint invalid paths. |
ci: code modified without change |
Strict mode detected source code modifications not covered by an active change |
Create or bind an active change via cabbage new <type> <id>. |
1---2name: project-docs-management3description: Enforce end-to-end project documentation lifecycle, change workflows, architecture decisions, validation, VitePress preview, Mermaid diagrams, and CI gates using cabbage.4metadata:5 source: https://skillmd.com/skills/devcxl/project-docs-management6---78# Cabbage Skill: Project Documentation Lifecycle & Workflow Gates910## 1. When to Use & Scenario Dispatch (Phase 0)1112Use this Skill whenever performing any software engineering, architecture, documentation, or operational activity.1314Before beginning, classify the incoming task against the 10 scenario archetypes:1516| Scenario Archetype | Cabbage Change Type | Workflow Path | Key Actions & Exit Criteria |17|---|---|---|---|18| **New Feature / Capability** | `feature` | Full Lifecycle | PRD -> Tech Spec (Testing Decisions) -> Tasks (Vertical Slices) -> Implementation -> Dual-Axis Review -> Merge |19| **Bug / Regression** | `bugfix` | Lightweight Corrective | Reproduce -> Failing Test (RED) -> Minimal Fix (GREEN) -> Regression Verify |20| **Production Incident / Hotfix** | `hotfix` / `incident` | Fast-Track Patch | Patch from release tag -> Minimal Fix -> Release PR -> Rollback plan |21| **Business Adjustment** | `feature` / `bugfix` | Change Management | Impact analysis -> Backward compatibility check -> Update spec -> Implement |22| **Refactoring** | `refactor` | Behavior-Preserving | Test safety net -> Stepwise refactor -> Differential/snapshot parity check |23| **Tech Debt Cleanup** | `refactor` | Behavior-Preserving Removal | Inventory unused assets -> Verify consumer references -> Delete -> Full regression |24| **Infrastructure Change** | `integration` / `refactor` | CI-as-Acceptance | Small incremental steps -> Push to CI -> Verify build pipeline & regression |25| **Documentation Update** | `feature` or direct docs | Docs-as-Code | Update canonical docs -> Terminology check -> Docs build verify (`cabbage docs build`) |26| **Rollback & Recovery** | `hotfix` | Controlled Rollback | Revert PR -> Create root-cause corrective change -> Clean worktrees |27| **Technical Research** | `architecture` | Evidence-Driven | Frame hypothesis -> Conduct research/POC -> Document findings & trade-offs |2829- *Reference: [`references/decision-tree.md`](references/decision-tree.md) for full classification tree and impact mappings.*3031---3233## 2. Core Principles & Anti-Rot Rules34351. **Single Source of Truth**: Every architectural or product fact lives in exactly one canonical document; all other docs link to it.362. **Current-State vs. Decision History**:37 - Current-state docs (`docs/01-product/`, `docs/03-architecture/system-design/`, `docs/05-api/`, `docs/13-operations/`) describe the system as it exists now and are updated in-place.38 - Decision-history docs (`ADR`, `RFC`, `postmortem`) are immutable historical records. Never rewrite history; explicitly supersede older decisions with new ones.393. **Content Signatures & Cascading Invalidation**: Verifying an artifact computes a cryptographic SHA-256 signature of its content, workflow schema, and upstream dependencies. Modifying an upstream artifact automatically invalidates downstream stages to `stale`.404. **Zero Placeholder & Strict Link Integrity**: Verification rejects any residual `TODO`, `TBD`, `FIXME`, or default scaffold prompts, as well as broken local relative links.415. **Atomic PR Delivery**: Code changes and their associated documentation changes must be committed and delivered in the same Pull Request.426. **Automated Specification Synchronization**: Running `cabbage sync` or `cabbage archive` automatically extracts verified specifications into the persistent `docs/` hierarchy.437. **No Final-v2-Copy Anti-Patterns**: Avoid filenames like `spec-v2-final.md`. Maintain stable paths and let Git manage version history.4445---4647## 3. Comprehensive Reference Index & Navigation4849Before or during execution, consult the following dedicated reference guides in `references/`:5051| Reference Document | Scope & Key Topics | When to Consult |52|---|---|---|53| [`references/cli.md`](references/cli.md) | Complete CLI syntax, subcommands, flags, exit codes, and JSON outputs | Executing or debugging any `cabbage` command |54| [`references/decision-tree.md`](references/decision-tree.md) | 10 scenario archetypes, classification tree, impact matrix, conditional activations | Classifying a new task or configuring impact flags |55| [`references/lifecycle.md`](references/lifecycle.md) | Change states (`active` / `archived`), stage state machine, SHA-256 signatures, stale triggers | Understanding state transitions or resolving gate blocks |56| [`references/directory-structure.md`](references/directory-structure.md) | Standard 22-category `docs/` tree layout and placement rules | Locating, creating, or moving long-lived documentation |57| [`references/document-types.md`](references/document-types.md) | Specifications, Testing Decisions, DAG vertical task slices, and lifecycle rules for 12 artifact types | Writing PRD, Tech Spec, ADR, RFC, API Design, Task DAGs, etc. |58| [`references/adoption.md`](references/adoption.md) | 7-phase flow for scanning, classifying, and migrating existing repository docs | Onboarding pre-existing project documentation |59| [`references/validation.md`](references/validation.md) | Automated validation rules, TDD protocol, and Dual-Axis Review framework | Troubleshooting `verify`/`validate` or reviewing PRs |60| [`references/linking-rules.md`](references/linking-rules.md) | Relative path resolution, stable heading anchors, cross-referencing rules | Writing Markdown links between files |61| [`references/naming-conventions.md`](references/naming-conventions.md) | Kebab-case naming, ADR/RFC numbering formats (`ADR-0001-...`), anti-patterns | Naming change workspaces, ADRs, RFCs, and files |62| [`references/diagrams.md`](references/diagrams.md) | Mermaid diagram syntax templates (Flowchart, Sequence, State, ER, Class, Git) | Creating or reviewing architectural diagrams |63| [`references/documentation-site.md`](references/documentation-site.md) | VitePress 1.6+ configuration, Mermaid integration, local dev preview, static build | Previewing or compiling the `docs/` site |64| [`references/enforcement.md`](references/enforcement.md) | CI gate configuration, branch protection, CODEOWNERS, agent security boundary | Setting up CI/CD pipelines or permission policies |65| [`references/ownership.md`](references/ownership.md) | Code-to-documentation parity, frontmatter metadata, team ownership boundaries | Assigning doc maintainers and PR reviewers |6667---6869## 4. Standard Operating Procedures (SOPs)7071### SOP 1: Feature & Capability Delivery Flow7273Follow this end-to-end workflow when implementing a new feature or business capability.7475```mermaid76flowchart TD77 Pre["0. Grill-Me Alignment (Context & Boundaries)"] --> A["1. cabbage doctor & new feature <id>"]78 A --> B["2. cabbage impact <id> --set ..."]79 B --> C["3. Draft PRD, Tech Spec (Options) & Task DAG (SOP)"]80 C --> D["4. cabbage verify <id> <stage>"]81 D --> E{"5. cabbage gate <id> implementation"}82 E -- Blocked --> C83 E -- Allowed --> F["6. cabbage tasks --export-dag & Parallel Subagent TDD"]84 F --> G["7. Mark Tasks Done [x] & Verify test-plan/release-plan"]85 G --> H["8. cabbage validate <id> & cabbage sync <id>"]86 H --> I{"9. Dual-Axis Review & cabbage gate <id> merge"}87 I -- Blocked --> F88 I -- Allowed --> J["10. Merge PR & cabbage archive <id>"]89```9091#### Step 0: Pre-Flight Context Alignment & Grill-Me Protocol92Before touching workflow files or generating artifacts, AI and human must establish a crystal-clear boundary consensus:93941. **Context & Codebase Exploration**:95 - Inspect existing codebase, canonical docs (`docs/`), and recent changes first.96 - Never ask questions that can be answered by reading the codebase.972. **Grill-Me Deep Alignment**:98 - Probe the intent iteratively: clarify the fundamental problem, business value, user personas, and hard constraints.99 - Explicitly define **In Scope** vs. **Explicit Non-Goals** to eliminate scope creep before it starts.100 - Formulate questions concisely (using structured options / questionnaires where applicable).1013. **Asymmetric Decision Framework (Frontal-Lobe Protection)**:102 - **AI Autonomous Decisions**: Micro-level technical details, private helper structures, internal naming, local refactorings, and test mocks are decided directly by AI without cognitive overhead for the human.103 - **Human Gate Decisions**: Strategic trade-offs, public API contracts, database schema migrations, billing/security policies, and breaking changes must be presented with options and decided by the human.1044. **Anchor in PRD**:105 - Record the validated assumptions, boundaries, and decision tiers into `.cabbage/changes/<change-id>/prd.md` under `## Grill-Me Alignment Summary` and `## Decision Boundaries`.106107#### Step 1: Initialize Workspace & Environment Check108Check environment prerequisites and initialize the change workspace:109110```bash111cabbage doctor112cabbage new feature <change-id>113```114- *Reference: [`references/naming-conventions.md`](references/naming-conventions.md) for `<change-id>` naming.*115116#### Step 2: Impact Analysis & Stage Activation117Evaluate affected technical domains and activate conditional stages:118119```bash120cabbage impact <change-id>121cabbage impact <change-id> --set api=true --set database=true --set security=true122```123- *Reference: [`references/decision-tree.md`](references/decision-tree.md) for impact field mappings.*124125#### Step 3: Author Artifacts, DAG Task Decomposition & Stage Verification126Inspect next ready stages, fill in the generated templates in `.cabbage/changes/<change-id>/`, remove all placeholders, and verify each stage:127128```bash129cabbage next <change-id>130# Edit .cabbage/changes/<change-id>/prd.md (contains Grill-Me outcomes and Decision Boundaries)131cabbage verify <change-id> prd132133# Edit tech-spec.md (must evaluate Architecture Options and include Testing Decisions)134cabbage verify <change-id> tech-spec135136# Edit tasks.md (must define Mermaid DAG, Parallel Groups, and Task SOP per slice)137cabbage verify <change-id> tasks138```139- **Architecture Options Protocol**:140 - In `tech-spec.md`, formulate 2 to 3 distinct architectural options (e.g. Minimal Low-Risk, Scalable Decoupled, Ideal Long-Term).141 - Compare benefits, costs, and risks explicitly before committing to the design.142- **Task DAG & Standard Operating Procedure (SOP)**:143 - Model tasks as a Directed Acyclic Graph (DAG) with Mermaid `flowchart TD`.144 - Slice tasks vertically (end-to-end observable behavior), avoiding horizontal tech layers.145 - Declare explicit `Blocked By` dependencies (true blocking only; no circular dependencies).146 - Every Task block must define its 4-step SOP:147 1. *[RED]* Test Seam: Define public test seam and write failing test.148 2. *[GREEN]* Implement: Minimal code to pass tests.149 3. *[REFACTOR]* Clean: Refactor, lint, type check, preserve behavior.150 4. *[VERIFY]* Validate: Run targeted verification command.151- *Reference: [`references/document-types.md`](references/document-types.md) for Testing Decisions, Architecture Options, and DAG Task SOP standards.* 152- *Reference: [`references/diagrams.md`](references/diagrams.md) for Mermaid architectural and DAG diagram templates.*153154#### Step 4: Pre-Implementation Gate Guard155Before writing source code, confirm the implementation gate passes:156157```bash158cabbage gate <change-id> implementation159```160*If this command exits with non-zero or outputs `BLOCKED`, resolve missing or stale stages before touching code.*161162#### Step 5: TDD Implementation & Subagent Parallel Orchestration163Execute tasks according to the DAG topological order:1641651. **DAG Inspection & Dispatch Export**:166 - Inspect DAG readiness and parallel groups:167 ```bash168 cabbage tasks <change-id>169 cabbage tasks <change-id> --export-dag170 ```171 - Exported plans can be dispatched directly to isolated worker subagents (e.g. parallel `subagent` calls) without cross-contamination.1722. **Standard Operating Procedure (Task SOP)**:173 - Each worker or subagent executes the 4-step SOP strictly against the designated test seam and verification command.174 - Mark task items `- [ ]` to `- [x]` as slices are verified.1753. **Topological Progression**:176 - Independent DAG branches run in parallel; convergence nodes run only after all prerequisites are marked green.177- *Reference: [`references/validation.md`](references/validation.md) for TDD behavioral protocol and Dual-Axis Review.*178179#### Step 6: Post-Implementation Verification & Plans180Complete and verify `test-plan.md` and `release-plan.md`:181182```bash183cabbage verify <change-id> tasks184cabbage verify <change-id> test-plan185cabbage verify <change-id> release-plan186```187188#### Step 7: Full Validation & Specification Sync189Validate all change constraints and synchronize specifications into `docs/`:190191```bash192cabbage validate <change-id>193cabbage sync <change-id>194cabbage docs build195```196- *Reference: [`references/directory-structure.md`](references/directory-structure.md) for synced target paths.* 197- *Reference: [`references/documentation-site.md`](references/documentation-site.md) for VitePress build details.*198199#### Step 8: Dual-Axis Review & Merge Gate200Execute Dual-Axis Review (Specification Axis + Convention Axis) and evaluate merge readiness:201202```bash203cabbage gate <change-id> merge204cabbage ci --base origin/main205```206- *Reference: [`references/validation.md`](references/validation.md) for Dual-Axis Review criteria.*207208#### Step 9: PR Merge & Archival209After merging the PR into the target branch:210211```bash212cabbage archive <change-id>213```214- *Reference: [`references/lifecycle.md`](references/lifecycle.md) for archival mechanics.*215216---217218### SOP 2: Existing Project Documentation Adoption Flow219220Follow this procedure when onboarding an existing repository with pre-existing documentation.221222```bash223# 1. Scaffold Cabbage base without touching existing docs224cabbage init225226# 2. Inventory all existing markdown documentation227cabbage adopt228229# 3. Apply suggested migrations or manually resolve review rows230cabbage adopt --apply231232# 4. Create adoption baseline change record233cabbage new feature adopt-existing-docs234235# 5. Verify links and site build236cabbage validate adopt-existing-docs237cabbage docs build238239# 6. Merge baseline PR and enable CI enforcement240```241- *Reference: [`references/adoption.md`](references/adoption.md) for the detailed 7-phase adoption guide.* 242- *Reference: [`references/enforcement.md`](references/enforcement.md) for branch protection and CI setup.*243244---245246### SOP 3: Architecture Change & ADR/RFC Decision Flow247248Follow this procedure when introducing systemic architectural changes, new design patterns, or major dependencies.2492501. **Create Architecture Workspace**:251 ```bash252 cabbage new architecture <change-id>253 ```2542. **Draft Decision Records & Proposals**:255 - Write `adr.md` following standard Context-Decision-Consequences format.256 - If broad cross-team discussion is required, draft `rfc.md`.257 - Embed Mermaid topology and sequence diagrams directly in the text.2583. **Verify Decision Artifacts**:259 ```bash260 cabbage verify <change-id> adr261 cabbage verify <change-id> tech-spec262 cabbage gate <change-id> implementation263 ```2644. **Sync to Persistent Architecture Tree**:265 ```bash266 cabbage sync <change-id>267 ```268 *This automatically registers `ADR-XXXX` under `docs/03-architecture/adr/`.*269- *Reference: [`references/document-types.md`](references/document-types.md) and [`references/naming-conventions.md`](references/naming-conventions.md).*270271---272273### SOP 4: Bugfix & Hotfix Flow274275Follow this streamlined procedure for defect corrections.2762771. **Create Bugfix / Hotfix Workspace**:278 ```bash279 cabbage new bugfix <change-id>280 # or for urgent production defects:281 cabbage new hotfix <change-id>282 ```2832. **Minimal Impact Assessment**:284 ```bash285 cabbage impact <change-id>286 ```287 *Only enable fields directly affected by the bugfix (e.g. `testing=true`).*2883. **Reproduce & Fix with TDD**:289 - Write a failing reproduction test (RED).290 - Apply minimal fix (GREEN).291 - Document root cause analysis in `tasks.md` and mark checklist items `- [x]`.2924. **Verify & Merge**:293 ```bash294 cabbage verify <change-id> tasks295 cabbage gate <change-id> merge296 ```297298---299300### SOP 5: Database & Data Migration Flow301302Follow this procedure when adding or modifying database schemas, tables, indexes, or running data backfills.3033041. **Create Migration Workspace & Set Impact**:305 ```bash306 cabbage new migration <change-id>307 cabbage impact <change-id> --set database=true --set deployment=true308 ```3092. **Author Database Design Artifact (`database-design.md`)**:310 - Define exact DDL / schema modifications.311 - Document forward migration steps and rollback procedures.312 - Include ER diagrams using Mermaid syntax.313 - Evaluate locking, zero-downtime constraints, and data safety.3143. **Verify & Execute Gate**:315 ```bash316 cabbage verify <change-id> database-design317 cabbage verify <change-id> tasks318 cabbage gate <change-id> implementation319 ```3204. **Sync & Merge**:321 ```bash322 cabbage sync <change-id>323 cabbage gate <change-id> merge324 ```325326---327328### SOP 6: Production Incident & Postmortem Flow329330Follow this procedure to document live service outages, root cause analysis, and preventative actions.3313321. **Create Incident Workspace**:333 ```bash334 cabbage new incident <incident-id>335 ```3362. **Document Incident Timeline & Postmortem**:337 - Record exact UTC timeline in `incident.md`.338 - Conduct 5-Why root cause analysis in `postmortem.md`.339 - List actionable preventative tasks with assigned owners.3403. **Verify & Archive into Incident History**:341 ```bash342 cabbage verify <incident-id> incident343 cabbage verify <incident-id> postmortem344 cabbage sync <incident-id>345 cabbage archive <incident-id>346 ```347 *Archived records permanently reside in `docs/15-incidents/`.*348349---350351## 5. Long-Session Context Management & Handoff352353During extended execution or when switching between major phases:3543551. **Context Pressure Mitigation**: When conversation history grows large or when pausing work:356 - Produce a concise handoff record under `docs/dev/handoff-<YYYY-MM-DD>.md` summarizing:357 - Current change ID and phase.358 - Completed stages and verified artifacts.359 - Active tasks in progress and immediate next step.360 - Key files created/modified.3612. **Session Resumption**:362 - Check existing changes: `cabbage status`363 - Inspect ready actions: `cabbage next <change-id>`364 - Resume directly from the next unblocked stage rather than re-scanning the entire project.365366---367368## 6. Command Quick Reference369370```bash371# Environment & Diagnosis372cabbage doctor # Diagnostic check373cabbage init # Greenfield init374cabbage adopt [--apply] # Adopt existing docs375376# Workspace & Stages377cabbage new <type> <change-id> # Create change workspace378cabbage status [change-id] # View stage progress379cabbage next <change-id> # View ready/blocked stages380cabbage impact <change-id> [--set k=v] # Inspect or update impact matrix381cabbage discard <change-id> # Remove active change382383# Verification & Gates384cabbage verify <change-id> <stage> # Verify single artifact385cabbage validate [<change-id> | --all] # Validate markdown & links386cabbage gate <change-id> implementation|merge # Evaluate lifecycle gate387388# Sync, Archive & CI389cabbage sync <change-id> # Extract specs into docs/390cabbage archive <change-id> # Archive completed change391cabbage ci --base <git-ref> # CI diff & gate runner392393# Documentation Site394cabbage docs install|dev|build # VitePress lifecycle395```396- *Reference: [`references/cli.md`](references/cli.md) for full parameter specifications and exit codes.*397398---399400## 7. Troubleshooting & Common Failure Modes401402| Error / Failure | Root Cause | Resolution |403|---|---|---|404| `verify: contains placeholder: ...` | File contains `TODO`, `TBD`, `FIXME`, or default template prompt text | Replace placeholder text with real content. |405| `verify: unchecked tasks remain` | `tasks.md` contains `- [ ]` unchecked checklist items | Mark completed items as `- [x]` after implementation. |406| `gate implementation: BLOCKED` | Required pre-implementation artifacts are unverified (`pending`) or `stale` | Run `cabbage next <id>` and verify unready stages with `cabbage verify`. |407| `stage status: stale` | Upstream artifact, workflow definition, or impact flag was modified | Review the artifact against updated upstream dependencies, then re-run `cabbage verify <id> <stage>`. |408| `validate: broken link ...` | A relative link in Markdown references a nonexistent file or anchor | Check relative path depth or update heading anchor slug. See [`references/linking-rules.md`](references/linking-rules.md). |409| `docs build: failed` | VitePress dead link check or unclosed code fence | Run `cabbage validate --all` to pinpoint invalid paths. |410| `ci: code modified without change` | Strict mode detected source code modifications not covered by an active change | Create or bind an active change via `cabbage new <type> <id>`. |