ln-111-root-docs-creator

Paths: File paths (references/, ../ln-*) are relative to this skill directory.

Root Documentation Creator

Type: L3 Worker

L3 Worker that creates 7 root documentation files using templates and Context Store from coordinator.

Purpose & Scope

• Creates 7 root documentation files (entry points for AI agents)
• Receives Context Store from ln-110-project-docs-coordinator
• Replaces placeholders with project-specific data
• Self-validates structure and content (22 questions)
• Never gathers context itself; uses coordinator input

Inputs

From coordinator:

• contextStore: Key-value pairs with all placeholders
  • PROJECT_NAME, PROJECT_DESCRIPTION
  • TECH_STACK_SUMMARY
  • DEV_COMMANDS (from package.json scripts)
  • DATE (current date)
  • ENABLE_WORKFLOW_PRINCIPLES (optional boolean; default false) — when true, expands the {{WORKFLOW_PRINCIPLES_BLOCK}} placeholder in AGENTS.md with the content of references/templates/agents_md_workflow_principles.md
• targetDir: Project root directory

MANDATORY READ: Load references/docs_quality_contract.md, and references/agent_instructions_writing_guide.md (the canonical writing guide for AGENTS.md / CLAUDE.md). Optional rule catalog: load references/docs_quality_rules.json only when exact rule IDs, path matrices, or allowlisted placeholder exceptions are needed.

Documents Created

File	Target Sections	Questions
AGENTS.md	Quick Navigation, Agent Entry, Critical Rules, (optional) Workflow Principles, Development Commands, Maintenance	Q1-Q6
CLAUDE.md	@AGENTS.md import + ## Claude Code delta (≤20 lines total)	Q1-Q6
docs/README.md	Quick Navigation, Agent Entry, Documentation Map, Maintenance	Q7-Q13
docs/documentation_standards.md	Quick Reference (60+ requirements), 12 main sections, Maintenance	Q14-Q16
docs/principles.md	Core Principles (8), Decision Framework, Anti-Patterns, Verification, Maintenance	Q17-Q22

Workflow

Phase 1: Receive Context

1. Parse Context Store from coordinator
2. Validate required keys present (PROJECT_NAME, PROJECT_DESCRIPTION)
3. Set defaults for missing optional keys (ENABLE_WORKFLOW_PRINCIPLES defaults to false)

Phase 2: Create Documents

For each document (AGENTS.md, CLAUDE.md, docs/README.md, docs/documentation_standards.md, docs/principles.md):

1. Check if file exists (idempotent)
2. If exists: skip with log
3. If not exists:
   • Copy template from references/templates/
   • For AGENTS.md: enforce the shared header contract (SCOPE, DOC_KIND, DOC_ROLE: canonical, READ_WHEN, SKIP_WHEN, PRIMARY_SOURCES) and the top-section contract (## Quick Navigation, ## Agent Entry, ## Critical Rules, ## Maintenance)
   • For AGENTS.md: if ENABLE_WORKFLOW_PRINCIPLES=true, replace the {{WORKFLOW_PRINCIPLES_BLOCK}} placeholder with the full content of references/templates/agents_md_workflow_principles.md; otherwise strip the placeholder line and its leading comment
   • For CLAUDE.md: use the import-stub template (claude_md_template.md). It contains DOC_ROLE: derived, a single @AGENTS.md line, and a bounded harness-specific delta. Do not inline any AGENTS.md content
   • For docs/principles.md: prefer normalized principle inputs already present in Context Store
   • If project-specific principles are absent, keep the template structure and fill only facts supported by current project sources
   • Replace {{PLACEHOLDER}} tokens with Context Store values
   • Never leave template markers in published root docs
   • If data is missing: omit the claim or use a concise neutral fallback, but do NOT emit [TBD: ...]
   • Write file

Root entrypoint rule (canonical model):

• AGENTS.md is the single canonical source of content. It holds the Critical Rules table, MCP Tool Preferences, Navigation, Development Commands, and optional Workflow Principles.
• CLAUDE.md is a Claude Code-specific stub that contains @AGENTS.md plus a ## Claude Code delta with harness-specific rules (≤20 lines total, ≤50 absolute max). Do not duplicate AGENTS.md content.
• Claude Code expands @path imports into the session context at launch, so the imported AGENTS.md is available automatically.
• Harness delta content: command terminology (/compact, /memory show), storage pointers (~/.claude/projects/<project>/memory/), and Claude-only features (.claude/rules/ with paths: frontmatter, nested on-demand loading).

Phase 3: Self-Validate

For each created document:

1. Check SCOPE tag in first 12 lines
2. Check metadata markers (DOC_KIND, DOC_ROLE, READ_WHEN, SKIP_WHEN, PRIMARY_SOURCES)
3. For AGENTS.md: check Quick Navigation, Agent Entry, Critical Rules, Maintenance
4. For CLAUDE.md: check @AGENTS.md import line is present and the file is ≤50 lines
5. Check required sections (from questions_root.md)
6. Check docs-quality contract compliance (no forbidden placeholders, no leaked template metadata)
7. Check POSIX endings (single newline at end)
8. Auto-fix issues where possible

Phase 4: Return Status

Return to coordinator:

{
  "created_files": ["AGENTS.md", "CLAUDE.md", "docs/README.md", "docs/documentation_standards.md", "docs/principles.md"],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": ["AGENTS.md", "CLAUDE.md", "docs/README.md", "docs/documentation_standards.md", "docs/principles.md"],
    "owners": {
      "AGENTS.md": "ln-111-root-docs-creator",
      "CLAUDE.md": "ln-111-root-docs-creator",
      "docs/README.md": "ln-111-root-docs-creator",
      "docs/documentation_standards.md": "ln-111-root-docs-creator",
      "docs/principles.md": "ln-111-root-docs-creator"
    }
  },
  "validation_status": "passed"
}

Critical Notes

Core Rules

• Idempotent: Never overwrite existing files; skip and log
• No context gathering: All data comes from coordinator's Context Store
• Publishable output: Root docs must not contain [TBD: ...], TODO, or leaked template metadata
• Language: All root docs in English (universal standards)
• SCOPE tags: Required in first 10 lines of each file (HTML comments are stripped from Claude Code's injected context but stay visible to maintainers and auditors)
• Canonical-stub root model: AGENTS.md is the single source; CLAUDE.md is an @AGENTS.md import plus bounded harness delta. See references/agent_instructions_writing_guide.md for rationale and anti-patterns.

NO_CODE_EXAMPLES Rule (MANDATORY)

Root documents define navigation and standards, NOT implementations:

• FORBIDDEN: Code blocks, implementation snippets
• ALLOWED: Tables, links, command examples (1 line)
• TEMPLATE RULE: All templates include <!-- NO_CODE_EXAMPLES: ... --> tag - FOLLOW IT

Stack Adaptation Rule (MANDATORY)

• All external links must match project stack (detected in Context Store)
• .NET project → Microsoft docs; Node.js → MDN, npm docs; Python → Python docs
• Never mix stack references (no Python examples in .NET project)

Format Priority (MANDATORY)

Tables/ASCII > Lists (enumerations only) > Text (last resort)

Runtime Summary Artifact

MANDATORY READ: Load references/docs_generation_summary_contract.md

Accept optional summaryArtifactPath.

Summary kind:

• docs-generation

Required payload semantics:

• worker = "ln-111"
• status
• created_files
• skipped_files
• quality_inputs
• validation_status
• warnings

Write the summary to the provided artifact path or return the same envelope in structured output.

Definition of Done

• Context Store received and validated
• Root documents created (or skipped if exist)
• All placeholders replaced; no [TBD: ...] markers or template metadata remain in root docs
• CLAUDE.md contains exactly one @AGENTS.md line and a bounded harness delta (≤50 lines total)
• If ENABLE_WORKFLOW_PRINCIPLES=true: the workflow principles shard is expanded in AGENTS.md; if false: the placeholder line is stripped
• Self-validation passed (SCOPE, metadata markers, top sections, Maintenance, POSIX)
• Actuality verified: all document facts match current code (paths, functions, APIs, configs exist and are accurate)
• Status returned

Reference Files

• Templates: references/templates/agents_md_template.md, references/templates/claude_md_template.md, references/templates/agents_md_workflow_principles.md, references/templates/docs_root_readme_template.md, references/templates/documentation_standards_template.md, references/templates/principles_template.md
• Questions: references/questions_root.md (Q1-Q22)
• Writing guide: references/agent_instructions_writing_guide.md (canonical rationale for the @AGENTS.md import pattern, size budgets, anti-patterns)
• Environment state: references/environment_state_contract.md (detection and bootstrap pattern)

---

Version: 2.1.0 Last Updated: 2025-01-12