project-narrator#

A workflow for maintaining a living document that can reconstruct your entire project from scratch. Not just documentation — a disaster recovery prompt.

The PROJECT-NARRATIVE.md file answers one question: "If everything disappeared except this file, could someone rebuild the project?" If yes, your narrative is complete.

Commands#

narrator generate#

Scan the workspace and generate a PROJECT-NARRATIVE.md from scratch.

Workflow:

1. Run scripts/generate.py in the project root to produce a scaffold
2. Review the scaffold — it captures structure, not intent
3. Fill in the sections the script can't infer: WHY decisions were made, design principles, known issues, security model
4. The script detects:
   • Package managers: package.json, pyproject.toml, Cargo.toml, go.mod
   • Infrastructure: Dockerfile, docker-compose, wrangler.toml/jsonc, vercel.json, serverless.yml
   • Git remote URL and recent commit history (last 20)
   • Source file counts by language
   • Scripts directory with first-line comments
   • Environment variables from .env.example
   • API route patterns from source (Express, FastAPI, Next.js, Hono)

bash

python3 scripts/generate.py --workspace /path/to/project
python3 scripts/generate.py --workspace /path/to/project --output docs/NARRATIVE.md

After running the script, the agent should:

• Read the generated scaffold
• Explore the codebase to understand architecture and intent
• Fill in Design Principles, Known Issues, Security Model
• Check for OpenClaw cron jobs ( openclaw cron list) and document them
• Add credential/ID references (without secrets — just names and where they're stored)

narrator audit#

Compare an existing narrative against reality. Flag drift.

Workflow:

1. Run scripts/audit.py against the project root
2. Review findings by severity (CRITICAL > WARNING > INFO)
3. Present findings to the user — don't auto-fix without asking

bash

python3 scripts/audit.py --workspace /path/to/project
python3 scripts/audit.py --workspace /path/to/project --narrative docs/NARRATIVE.md
python3 scripts/audit.py --workspace /path/to/project --check-urls

Severity levels:

• CRITICAL: Referenced file doesn't exist, documented dependency removed, config structure changed
• WARNING: New files not documented, dependency version drift, undocumented scripts
• INFO: Minor structural differences, new commits since last update

narrator update#

Incrementally update the narrative based on recent changes.

Workflow:

1. Read the existing PROJECT-NARRATIVE.md
2. Find the last-updated date from the file
3. Run git log --since="LAST_DATE" to find changes
4. Identify significant changes:
   • New or deleted files
   • Changed config files (package.json, env, infra configs)
   • New dependencies
   • New scripts or API routes
5. Update the Changelog section with a summary
6. Flag sections that likely need manual review based on what changed
7. Update the "Last updated" date

The agent should not blindly rewrite sections — flag what changed and let the user decide how to update the narrative prose.

narrator report#

Generate a health report without modifying anything.

Workflow:

1. Run the audit workflow
2. Check git activity (commits per week, active contributors)
3. Check narrative freshness (days since last update)
4. Produce a summary:
   • Narrative age and staleness risk
   • Number of drift findings by severity
   • Sections most likely outdated
   • Recommendation: update, regenerate, or "looks good"

Template Structure#

The narrative follows this structure (flexible, not rigid):

markdown

# Project Name: The Complete Narrative
*Last updated: YYYY-MM-DD*

## What Is This Project?
## Current Status
## Architecture
## Infrastructure
## Pipeline / Workflow
## API Routes
## Scripts
## Configuration
## Security Model
## Known Issues
## Design Principles
## Changelog
## Key Credentials & IDs
## File Map

See references/narrative-template.md for a complete template with guidance comments. See references/examples.md for examples of well-written narrative sections.

Configuration#

Create narrator.json in your workspace root to customize behavior:

json

{
  "schedule": "weekly",
  "audit_on_commit": false,
  "max_tokens_per_run": 5000,
  "sections": {
    "changelog": true,
    "file_map": true,
    "credentials": true
  }
}

Schedule Options#

• "manual" — only runs when you ask (default)
• "weekly" — runs audit every 7 days via heartbeat check
• "daily" — runs audit daily (higher token cost, ~2-5K tokens per audit)
• "on_commit" — runs after significant git commits (10+ files changed)

Token Cost Estimates#

• Generate (from scratch): ~3-8K tokens depending on project size
• Audit (compare): ~2-5K tokens
• Update (incremental): ~1-3K tokens
• Report (read-only): ~1-2K tokens

Recommendation: Start with "manual" and run audits weekly. Only switch to "daily" for fast-moving projects with multiple contributors.

Token Efficiency#

The skill is designed to be token-conscious:

• Scripts run locally (Python stdlib) — zero LLM tokens for scanning
• Only the narrative TEXT goes through the LLM for generation/update
• Audit is pure filesystem comparison — no LLM needed
• Incremental updates only process git diff, not the whole project

Key Principles#

Capture WHY, not just WHAT. Any tool can list files. The narrative explains why the project is structured this way, what alternatives were considered, and what mistakes were made along the way.

Known issues are features. Documenting bugs, tech debt, and past mistakes prevents repeating them. A narrative that only shows the happy path is incomplete.

Design Principles is the most important section. Architecture can be reverse-engineered from code. Design principles cannot. "We chose SQLite over Postgres because this runs on edge workers" — that's the kind of decision that saves hours of confusion.

Self-contained. Any agent or developer reading the narrative should understand the full project without needing to ask follow-up questions. If they have to dig through code to understand the narrative, the narrative failed.

Fresh build every time. Narratives are always regenerated from scratch — never patched or appended. This prevents drift from accumulating across versions. When you run narrator generate, the old narrative is archived and a completely new one is built by scanning the current state. No assumptions carried forward from previous versions.

Automatic archiving. Every time a narrative is regenerated, the previous version is saved to narrative-archive/NARRATIVE-{timestamp}.md. This gives you rollback ability and a history of how the project evolved. Archives are cheap — keep them.

Living document. Regenerate after significant changes or weekly via cron. A stale narrative is worse than no narrative — it actively misleads.

No secrets in the narrative. Reference where credentials are stored, never the credentials themselves. "API key stored in ~/.openclaw/secrets/stripe.key" — not the key.

Automation#

Weekly cron (OpenClaw)#

Set up a weekly narrative health check:

text

openclaw cron add --schedule "0 9 * * 1" --prompt "Run narrator report on /path/to/project. If there are CRITICAL findings, notify me. Otherwise log to memory." --label "narrator-weekly"

Post-deploy hook#

After significant deploys, run narrator update to capture what changed.

About#

project-narrator was built during the development of AgentWyre, an AI intelligence wire service, where maintaining accurate project state across dozens of cron jobs, API endpoints, and daily pipelines proved that living documentation isn't optional — it's infrastructure. Born from building AgentWyre, the narrative pattern kept its complex multi-language, multi-pipeline system coherent across hundreds of changes in its first week of operation.