ln-111-root-docs-creator

SKILL.md

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

Parse Context Store from coordinator

Validate required keys present (PROJECT_NAME, PROJECT_DESCRIPTION)

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):

Check if file exists (idempotent)

If exists: skip with log

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:

Check SCOPE tag in first 12 lines

Check metadata markers (DOC_KIND, DOC_ROLE, READ_WHEN, SKIP_WHEN, PRIMARY_SOURCES)

For AGENTS.md: check Quick Navigation, Agent Entry, Critical Rules, Maintenance

For CLAUDE.md: check @AGENTS.md import line is present and the file is ≤50 lines

Check required sections (from questions_root.md)

Check docs-quality contract compliance (no forbidden placeholders, no leaked template metadata)

Check POSIX endings (single newline at end)

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