Project Knowledge Harness

project-knowledge-harness

A lightweight, file-based memory harness for any software project.

Three surfaces, sharply separated by time direction and access pattern:

Plus, in projects that already have agent contracts, AGENTS.md Hard invariants answer "What rules MUST agents follow?". Pitfalls graduate to Hard invariants when serious enough — see references/when-to-add-docs.md.

When to use this skill

Use this skill when the user surfaces any of:

• A long-term TODO list with no home, or a messy TODO.md that needs structure (signals: "where should ideas go?", "maybe later", "工程量太大需要再評估")
• A debugging session worth saving (signals: "keep solving the same problem twice", "save this troubleshooting", "踩過的坑", "TROUBLESHOOTING.md scattered across docs/")
• A request to consolidate IDEAS.md / ROADMAP.md / WISHLIST.md / LESSONS.md files

Do NOT use this skill for active sprint planning (use issue trackers), ephemeral agent scratchpads (use .claude/plans/), or current feature documentation (use docs/).

How to apply this skill (default workflow)

The skill bundles five scripts and several templates. Default to the init script for setup, and default to add-todo.sh / sweep-inbox.sh for capture rather than asking the agent to edit TODO.md by hand.

scripts/
  init.sh         # one-shot setup of TODO.md + backlog/ + pitfalls/
                  # + agent guidance + README snippet
  todo-kanban.sh  # validate TODO.md format and render kanban-style board
  add-todo.sh     # insert a structured entry into the right ## P* lane
  promote-todo.sh # move an active TODO item to ## Done with the right syntax
  sweep-inbox.sh  # triage backlog/inbox.md into TODO.md via add-todo.sh

1. Run scripts/init.sh against the target repo

scripts/init.sh \
  --target /path/to/project \
  --project-name "My Project" \
  --deployment chezmoi   # or npm | pip | docker | none

The script:

1. Creates TODO.md, backlog/README.md, pitfalls/README.md from assets/*.template, substituting placeholders.
2. Appends an agent-guidance snippet to AGENTS.md / CLAUDE.md (auto-detected, override with --agent-contract).
3. Appends a "Roadmap & lessons learned" section to README.md.
4. Runs scripts/todo-kanban.sh --validate-only TODO.md so any drift is caught immediately.
5. Prints the deployment-exclusion lines you should add manually (it does not edit ignore files — see references/deployment-exclusion.md).

init.sh is idempotent: existing files are skipped unless --force is given, and snippets append only if a sentinel marker is missing.

2. Mid-conversation, when the user surfaces a "maybe later" idea

Signals: "maybe later", "nice to have", "if I'm interested", "工程量太大需要再評估", "先記下來", "not now but…".

1. If TODO.md doesn't exist yet, run scripts/init.sh first.

2. Default path — call scripts/add-todo.sh with the priority, effort, title, and description. This inserts the canonical line into the right ## P* lane and re-validates. Add --backlog if the conversation produced enough investigation that a backlog/<slug>.md doc is worth scaffolding.

   scripts/add-todo.sh --priority "P?" --effort M \
     --title "Try Rspress for docs" \
     --description "Evaluate AI-native docs framework alternative"
   

3. Quick-capture path — append to backlog/inbox.md when the user isn't sure of priority/effort yet, or is mid-thought:

   echo "- $UNSTRUCTURED_THOUGHT" >> backlog/inbox.md
   

   Later (this session or next), run scripts/sweep-inbox.sh to formalize the loose lines into TODO.md one at a time. The sweeper prompts for missing fields per line; in --batch mode it only processes lines that already have priority=… effort=… title="…" description="…" pairs and leaves ambiguous ones in place.

4. Manual edit path — only when scripts can't help. Use the syntax from references/tag-schema.md and run scripts/todo-kanban.sh --validate-only afterwards.

5. If you wrote a backlog/<slug>.md (either via --backlog or by hand), make sure the TODO line ends with → [research](backlog/<slug>.md) so the index points to the doc.

3. Mid-conversation, when you finish debugging something tricky

Signals: "phew, that took a while", "weird, the error didn't say anything about X", "this is the third time we've hit this", or you find yourself reconstructing context that isn't in any doc.

1. Create pitfalls/<symptom-slug>.md immediately from assets/pitfall-doc.md.template, while the trace is fresh. Title the doc by the symptom, not the root cause — you'll search by what you're seeing, not by what you eventually learned.
2. Copy verbatim error messages — never paraphrase, it kills grep-ability.
3. If the trap is severe (silent corruption / cross-machine recurrence / non-obvious workaround), surface it: "should this graduate to a Hard invariant in AGENTS.md?" — see references/when-to-add-docs.md.

4. When implementing a TODO.md item

In the same commit:

1. Run scripts/promote-todo.sh --title "<substring>" --summary "<what shipped>". It removes the active line and inserts the dated Done entry, then re-validates. It refuses to run if the substring matches zero or more than one active item.
2. If a backlog/<slug>.md exists, set its Status: shipped (don't delete — historical record may inform adjacent decisions).
3. If shipping uncovered a trap, write a pitfalls/<slug>.md for it.

When a TODO entry needs a backlog/ doc, when a debug needs a pitfalls/ doc

Decision rules and the upgrade path to AGENTS.md invariants live in references/when-to-add-docs.md. Read it the first time you set up the harness; consult it again whenever you're unsure which surface a piece of knowledge belongs in.

Tag schema

Two orthogonal axes, validated by scripts/todo-kanban.sh. See references/tag-schema.md for the full schema, useful tag combinations, and the exact validator-checked syntax.

Anti-patterns

Common mistakes to avoid (e.g., spawning IDEAS.md alongside TODO.md, titling pitfalls by root cause, paraphrasing errors). Full list in references/anti-patterns.md.

Deployment exclusion

TODO.md, backlog/, and pitfalls/ are maintainer-facing repo metadata, not files to ship. Cheatsheet for chezmoi / npm / pip / Docker in references/deployment-exclusion.md. scripts/init.sh --deployment ... prints the exact lines to add.

Templates and bundled assets

• assets/TODO.md.template — TODO.md skeleton with example items per lane
• assets/backlog-README.md.template — backlog/ index + when-to-add rules
• assets/backlog-doc.md.template — single backlog doc (context-first)
• assets/pitfalls-README.md.template — pitfalls/ index + cross-reference table for traps documented elsewhere
• assets/pitfall-doc.md.template — single pitfall doc (symptom-first)
• assets/agent-guidance.md.template — snippet for AGENTS.md / CLAUDE.md
• assets/readme-roadmap.md.template — snippet for project README.md
• scripts/init.sh — one-shot setup
• scripts/todo-kanban.sh — validator + Markdown kanban renderer (also supports --json and --validate-only)
• scripts/add-todo.sh — structured insert into ## P* lane; --backlog also scaffolds backlog/<slug>.md
• scripts/promote-todo.sh — atomic active-→-Done move with re-validation
• scripts/sweep-inbox.sh — triage backlog/inbox.md → add-todo.sh

Reference implementation

A live example of this harness is at daviddwlee84/dotfiles:

• TODO.md, backlog/, pitfalls/ directories at repo root
• AGENTS.md ### Long-term backlog → TODO.md + backlog/ and ### Past pitfalls → pitfalls/ sections
• README.md ## Roadmap & lessons learned section