ln-111-root-docs-creator

---
name: ln-111-root-docs-creator
description: Creates root documentation files (AGENTS.md, CLAUDE.md, docs/README.md, standards, principles). Use for initial project doc setup.
license: MIT
---

> **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:
```json
{
  "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