Project Docs Management

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:

• Reference: references/decision-tree.md for full classification tree and impact mappings.

2. Core Principles & Anti-Rot Rules

1. Single Source of Truth: Every architectural or product fact lives in exactly one canonical document; all other docs link to it.
2. 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.
3. 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.
4. Zero Placeholder & Strict Link Integrity: Verification rejects any residual TODO, TBD, FIXME, or default scaffold prompts, as well as broken local relative links.
5. Atomic PR Delivery: Code changes and their associated documentation changes must be committed and delivered in the same Pull Request.
6. Automated Specification Synchronization: Running cabbage sync or cabbage archive automatically extracts verified specifications into the persistent docs/ hierarchy.
7. 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/:

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:

1. Context & Codebase Exploration:
   • Inspect existing codebase, canonical docs (docs/), and recent changes first.
   • Never ask questions that can be answered by reading the codebase.
2. 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).
3. 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.
4. 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:
    1. [RED] Test Seam: Define public test seam and write failing test.
    2. [GREEN] Implement: Minimal code to pass tests.
    3. [REFACTOR] Clean: Refactor, lint, type check, preserve behavior.
    4. [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:

1. DAG Inspection & Dispatch Export:
   • Inspect DAG readiness and parallel groups:

     cabbage tasks <change-id>
     cabbage tasks <change-id> --export-dag
     

   • Exported plans can be dispatched directly to isolated worker subagents (e.g. parallel subagent calls) without cross-contamination.
2. 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.
3. 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.

1. Create Architecture Workspace:

   cabbage new architecture <change-id>
   

2. 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.
3. Verify Decision Artifacts:

   cabbage verify <change-id> adr
   cabbage verify <change-id> tech-spec
   cabbage gate <change-id> implementation
   

4. 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.

1. Create Bugfix / Hotfix Workspace:

   cabbage new bugfix <change-id>
   # or for urgent production defects:
   cabbage new hotfix <change-id>
   

2. Minimal Impact Assessment:

   cabbage impact <change-id>
   

   Only enable fields directly affected by the bugfix (e.g. testing=true).
3. 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].
4. 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.

1. Create Migration Workspace & Set Impact:

   cabbage new migration <change-id>
   cabbage impact <change-id> --set database=true --set deployment=true
   

2. 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.
3. Verify & Execute Gate:

   cabbage verify <change-id> database-design
   cabbage verify <change-id> tasks
   cabbage gate <change-id> implementation
   

4. 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.

1. Create Incident Workspace:

   cabbage new incident <incident-id>
   

2. 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.
3. 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:

1. 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.
2. 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