Core Principles

Full principles with rationale: references/principles.md

Security/ops guardrails:

• Never write secrets into generated files.
• Do not run destructive shell commands.
• Prefer offline, unit-level validation; avoid networked/E2E commands unless explicitly asked.

Inputs

RAW ARGUMENTS: $ARGUMENTS

If $ARGUMENTS contains --help or is exactly help, print a usage guide without modifying the repo.

Parsing

1. Extract flags: --help, --agents, --claude, --both (default: --both)
2. Parse remaining as: [mode] [scope...] (scope can be space/comma separated)
3. Defaults: mode=auto, scope=.

Modes

quick-start: Create from scratch. Ask if scope is ambiguous (monorepo signals). Offer CLAUDE.md consolidation if standalone CLAUDE.md exists.

update: Incremental by default. Run scripts/check_staleness.py to assess what changed. Only update affected sections. Load references/incremental-update-workflow.md for the full algorithm. Falls back to full scan if docs are severely stale or malformed.

evaluate: Everything in update, plus evaluate against principles above and propose/apply improvements.

auto (default): No docs → quick-start. Has docs → update + evaluate. Zero user input. Smart defaults for everything. Automatic CLAUDE.md consolidation, nested doc creation, docs/ generation for cross-cutting topics. Suitable for CI and background jobs.

Execution Plan

1. Determine Root and Scope

• Git root is the anchor (or provided scope directory).
• Detect monorepo signals (workspaces, multiple manifests).
• In auto mode: infer scope from git status / git diff --name-only if not provided.
• Cross-cutting system scope: when the user provides a system name + multiple code paths (e.g., "ML Inference Pipeline" spanning ml/training/, services/triton/, api/routes/inference.py), docs live alongside the primary module. See references/docs-structure.md Scale D for details.
• Scope guardrail: respect explicit scope — don't create docs in parent/sibling dirs.
• For update mode: run scripts/check_staleness.py on existing AGENTS.md.

2. Discover Authoritative Context

Read (minimal, targeted): README, build/test/lint configs, package manifests, Makefile/Taskfile, CI workflows, repo layout.

2b. Discover and Classify Pre-Existing Documentation

Run this before writing any new files. Load references/existing-docs-migration-workflow.md for the full algorithm.

1. Find non-standard doc directories (ai_agent_docs/, agent-docs/, context/, llm-docs/)
2. Find existing docs/*.md files without skill-generated YAML frontmatter
3. Read every file found — do not skip based on filename or apparent size
4. Classify each file's content: Architectural (→ docs/), Module Operational (→ nested AGENTS.md), Fast-Changing (discard), or Unverifiable (keep in place)
5. Verify accuracy of Architectural and Module Operational content (path checks, command existence)
6. Build a migration manifest: source → destination for every piece of content
7. Only proceed to Step 4 after the manifest is complete

Unverifiable content: if content cannot be confirmed without running E2E or networked operations, keep it at its current path. Do not delete it. Flag it in the Step 6 report with reason.

Scope boundary: This step classifies pre-existing content to inform routing tables and AGENTS.md updates. Actual file moves, docs/ restructuring, and index creation in docs/ are owned by the docs-workflow skill. If running both skills, defer docs/ file operations to docs-workflow. If running context-engineering alone, execute the migration inline.

3. Derive Commands

Typical buckets: install/bootstrap, dev server, test, lint/format, typecheck, build. Validate each command. For test commands: attempt minimal safe fast execution. See resources/generated-doc-spec.md for detailed validation rules.

4. Write or Update Files

Follow resources/generated-doc-spec.md for the exact output structure. All generated docs/*.md content files get frontmatter per resources/frontmatter-index-spec.md. AGENTS.md files do not get frontmatter.

Frontmatter rule — applies to created AND updated docs/*.md content files:

• If you create a new docs/ content file: add frontmatter.
• If you update an existing docs/ content file: check if frontmatter exists. If missing, add it.
• "I didn't create it" is not an excuse — if you touched it, it gets frontmatter.
• Exception — AGENTS.md files at any level are routing indexes, not content docs. They do not get frontmatter. Agents auto-discover AGENTS.md by convention; frontmatter adds no routing value.

Intent classification: when creating docs/ files, classify each by type (tutorial, how-to, explanation, reference) using the intent classification in references/docs-structure.md. Place into intent folders per the structure rules (folders from the start → sub-indexes when a folder hits 8+).

Docs index generation: when creating or updating docs/ files, also create/update docs/README.md (human progression index) and docs/AGENTS.md (agent routing index). See references/docs-structure.md for index specs.

File strategy:

• AGENTS.md is canonical. CLAUDE.md is a symlink.
• For update mode: use diff-based editing per references/incremental-update-workflow.md.
• Auto mode creates: nested AGENTS.md for modules with distinct workflows, docs/ files for cross-cutting topics, docs/architecture.md for repos with 3+ modules (template in resources/architecture-doc-template.md).
• For monorepos: generate cross-module dependency map per references/cross-module-dependency-map.md.

5. Validate

Run validation scripts, passing the git root as scope. The scripts automatically exclude _archive/, archive/, .git, .venv, node_modules, __pycache__, and vendored plugin docs (config/{tool}/plugins/*/docs/).

scripts/validate_frontmatter.py {git_root}    # Frontmatter exists, fields valid, ids unique
scripts/verify_references.py {git_root}       # All referenced paths exist

Expected false positives to ignore in the report:

• _archive/ files: intentionally archived docs for a different repo/context
• Files you did not create or modify in this run (pre-existing broken refs are not your responsibility)

When reporting validation results, distinguish between:

• New failures: broken refs in files you created/modified this run → fix before finishing
• Pre-existing failures: broken refs in unmodified files → report as-is, do not fix

In evaluate/auto mode: also apply rubric (conciseness, correctness, progressive disclosure quality). Specifically check that docs/AGENTS.md (if it exists) has YAML frontmatter and uses the intent-typed table format specified in resources/generated-doc-spec.md. If it predates the skill and lacks frontmatter or uses a different structure, flag it for update.

6. Report

Output in chat:

• Files created/updated (paths)
• Key changes (bullets)
• Validation log (commands + ✅/⚠️/⏸️)
• Symlink status (✅ exists / ⚠️ created / missing)
• Script results (frontmatter validation, reference checks)
• Pre-existing docs inventory (from Step 2b):
  • Files read (paths + line counts)
  • Migrated: source → destination for each file
  • Kept in place: path + reason (unverifiable / partially verified)
  • Discarded: path + reason + summary of what was in it
  • Source dirs/files removed only after all content accounted for
• Remaining unknowns or follow-ups

Do NOT paste full file contents unless asked.

Scripts

Deterministic validation tools in scripts/:

Bundled Content

Load only what the current step requires:

Resources (specs and templates for output):

References (guides and workflows):

Now Execute

Proceed in the parsed mode using the scope rules above.