Create Dev Docs Plan

create-dev-docs-plan

Purpose

Create a dev-docs task bundle that is implementation-ready and suitable for handoff (module-scoped by default).

The repository is module-first:

• Module dev-docs live under modules/<module_id>/dev-docs/
• Cross-module integration dev-docs live under modules/integration/dev-docs/

Decision gate (MUST)

Use create-dev-docs-plan when any of the following is true:

• Expected duration > 2 hours, or likely to span multiple sessions
• Work requires explicit handoff / context recovery documentation
• High-risk or cross-cutting change:
  • DB / schema migration
  • Auth / security changes
  • CI / CD / infrastructure changes
  • Multi-module or API boundary changes
  • Changes to .system/modular/ SSOT files
• Unclear scope requiring discovery before implementation
• Meaningful architectural / flow decision needed

Skip create-dev-docs-plan when all of the following are true:

• Trivial fix (< 30 min, well-defined scope)
• Single-file change (including adjacent tests / docs in same module)
• Simple refactor with clear scope (even if touching multiple files)
• No handoff expected

Note: Touching multiple folders (e.g., src/ + tests/ + docs) is NOT a sufficient trigger by itself.

Inputs

• Task statement
• Scope hint (if available): module id, or "integration"
• Any acceptance criteria / constraints

Outputs

A directory with a dev-docs bundle:

• 00-overview.md
• 01-plan.md
• 02-architecture.md
• 03-implementation-notes.md
• 04-verification.md
• 05-pitfalls.md

Scope resolution

Dev-docs can be placed in one of three locations:

Path confirmation rules (MUST)

Critical rule: NEVER create dev-docs under modules/ without explicit human confirmation of the full path. If confirmation is not obtained, fall back to .ai/.tmp/dev-docs/.

Procedure

1. Infer scope

   • If the task is clearly about a single module, treat the task as module-scoped.
   • If the task spans multiple modules (or involves scenario testing), treat the task as integration-scoped.
   • If scope is unclear:
     1. Ask the user to confirm module_id or integration.
     2. If user cannot decide or explicitly requests a temporary location, use .ai/.tmp/dev-docs/<task_slug>/ as the fallback.
   • If user explicitly specifies .ai/.tmp/dev-docs/ or "temporary", use that location directly without further scope confirmation.

2. Prefer resume over new creation

   • Check for existing tasks first:
     • Module: modules/<module_id>/dev-docs/active/
     • Integration: modules/integration/dev-docs/active/
     • Temporary: .ai/.tmp/dev-docs/
   • If an active task already matches the user's request, reuse the matching task and only update missing artifacts.
   • If you reuse an existing task, read these first before doing any work:
     • 03-implementation-notes.md
     • 05-pitfalls.md

3. Confirm path with user (MUST for non-temporary scope)

   • Propose a <task_slug> (kebab-case, e.g., fix-auth-middleware, add-checkout-flag).
   • For module/integration scope: present the full proposed path and wait for explicit user confirmation before creating any files:

     Proposed path: modules/<module_id>/dev-docs/active/<task_slug>/
     Please confirm this location, or specify a different one.
     

   • For temporary scope: propose the path but may proceed without waiting if user does not respond.

4. Create the dev-docs folder

   • Only after confirmation (for module/integration) or with temporary scope:
     • Module: modules/<module_id>/dev-docs/active/<task_slug>/
     • Integration: modules/integration/dev-docs/active/<task_slug>/
     • Temporary: .ai/.tmp/dev-docs/<task_slug>/

5. Create the bundle files from templates

   • Copy from ./templates/ into the task folder.
   • Fill in placeholders with task-specific content.
   • Set 03-implementation-notes.md:
     • Current status: planned
     • Last updated: YYYY-MM-DD

6. Register with project governance (recommended for non-temporary scope)

   • After creating the bundle under modules/, run sync to register the task in the project hub:

     node .ai/scripts/ctl-project-governance.mjs sync --apply --project main
     

   • This generates the .ai-task.yaml identity file and upserts the task into registry.yaml.
   • For temporary scope (.ai/.tmp/dev-docs/), skip this step (temporary tasks are not tracked by governance).

Notes

• Prefer linking to SSOT: module MANIFEST, .system/modular/flow_graph.yaml, and context registries.
• Keep dev-docs concise and operational (paths, commands, current status, concrete verification).

Execution sync rules (what "good" looks like)

Even though create-dev-docs-plan is docs-only, the workflow is designed to make execution robust:

• During implementation, keep these files current:
  • 01-plan.md (check off completed items; add newly discovered TODOs)
  • 03-implementation-notes.md (what changed + decisions + deviations)
  • 04-verification.md (commands run + results + blockers)
• Before context switch/handoff, run update-dev-docs-for-handoff.

Verification

• Confirm the dev-docs directory exists at the intended scope:
  • Module: modules/<module_id>/dev-docs/active/<task_slug>/
  • Integration: modules/integration/dev-docs/active/<task_slug>/
  • Temporary: .ai/.tmp/dev-docs/<task_slug>/
• Confirm the bundle files exist and are filled in (no empty placeholders).
• For non-temporary scope: confirm .ai-task.yaml exists in the task directory (created by sync), or suggest running:
  • node .ai/scripts/ctl-project-governance.mjs sync --apply --project main

Boundaries

• Do not implement code changes as part of create-dev-docs-plan. Only create/update dev-docs.
• Do not edit derived artifacts directly (e.g., docs/context/registry.json, .system/modular/*_index.yaml, modules/integration/compiled/*).
• If changes to SSOT are required (MANIFEST / flow_graph / scenarios), use the appropriate ctl scripts and record the change rationale in dev-docs.
• MUST NOT create dev-docs under modules/ (module or integration scope) without explicit human confirmation of the full path.
• MUST fall back to .ai/.tmp/dev-docs/ if human confirmation is not obtained for module/integration scope.

Included assets

• Templates: ./templates/*.md
• Examples: ./examples/

Coordination with plan-maker

Typical workflow:

1. For tasks requiring strategic alignment first, use plan-maker to create roadmap.md.
2. Use create-dev-docs-plan to create the implementation bundle (00-overview.md through 05-pitfalls.md).
3. Both artifacts coexist in the same dev-docs directory:

modules/<module_id>/dev-docs/active/<task_slug>/
  roadmap.md              # Macro-level planning (plan-maker)
  00-overview.md          # Goal, non-goals, acceptance criteria
  01-plan.md              # Implementation plan
  02-architecture.md      # Architecture design
  03-implementation-notes.md  # Current status + TODOs
  04-verification.md      # Verification commands + results
  05-pitfalls.md          # "Do not repeat" lessons

Writing tips

• Write purpose + outcome first in 00-overview.md.
• Add verification commands with expected results in 04-verification.md.
• Before finalizing, do a reader test: can a fresh agent answer "what do I do next?" using only the dev-docs bundle?

Converted and distributed by TomeVault — claim your Tome and manage your conversions.