english/.opencode/skills/docs/references/update-workflow.md

Update Workflow

Phase 1: Parallel Codebase Scouting

1. Scan the codebase and calculate the number of files with LOC in each directory (skip .claude, .opencode, .git, tests, node_modules, __pycache__, secrets, etc.)
2. Target directories that actually exist - adapt to project structure
3. Activate ck:scout skill to explore the code base and return detailed summary reports
4. Merge scout reports into context summary

Phase 1.5: Parallel Documentation Reading

You (main agent) must spawn readers - subagents cannot spawn subagents.

1. Count docs: ls docs/*.md 2>/dev/null | wc -l
2. Get LOC: wc -l docs/*.md 2>/dev/null | sort -rn
3. Strategy:
   • 1-3 files: Skip parallel reading, docs-manager reads directly
   • 4-6 files: Spawn 2-3 Explore agents
   • 7+ files: Spawn 4-5 Explore agents (max 5)
4. Distribute files by LOC (larger files get dedicated agent)
5. Each agent prompt: "Read these docs, extract: purpose, key sections, areas needing update. Files: {list}"
6. Merge results into context for docs-manager

Phase 2: Documentation Update (docs-manager Agent)

CRITICAL: You MUST spawn docs-manager agent via Task tool with merged reports and doc readings.

Pass the gathered context to docs-manager agent to update documentation:

• README.md: Update README (keep it under 300 lines)
• docs/project-overview-pdr.md: Update project overview and PDR
• docs/codebase-summary.md: Update codebase summary
• docs/code-standards.md: Update codebase structure and code standards
• docs/system-architecture.md: Update system architecture
• docs/project-roadmap.md: Update project roadmap
• docs/deployment-guide.md [optional]: Update deployment guide
• docs/design-guidelines.md [optional]: Update design guidelines

Additional requests

<additional_requests> $ARGUMENTS </additional_requests>

Phase 3: Size Check (Post-Update)

After docs-manager completes:

1. Run wc -l docs/*.md 2>/dev/null | sort -rn to check LOC
2. Use docs.maxLoc from session context (default: 800)
3. For files exceeding limit: report and ask user

Phase 4: Documentation Validation (Post-Update)

Run validation to detect potential hallucinations:

1. Run: node .opencode/scripts/validate-docs.cjs docs/
2. Display validation report (warnings only, non-blocking)
3. Checks: code references, internal links, config keys

Important

• Use docs/ directory as the source of truth.
• Do not start implementing.