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:

Surface	Time	Question it answers	Access pattern
TODO.md	Future	"What might we do later?"	Read top to bottom (priority lanes)
backlog/<slug>.md	Future	"What was the analysis behind this idea?"	Indexed from TODO.md
pitfalls/<slug>.md	Past	"I see error X — has this happened before?"	Grep symptom keywords

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, or td for in-flight agent work — see "Optional: td integration" below), ephemeral agent scratchpads (use .claude/plans/), or current feature documentation (use docs/).

How to apply this skill (default workflow)

The skill bundles six 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
  start-todo.sh   # optional: open/reuse a td issue for an item (no-op without td)
  _lib/           # shared TODO parser + td bridge (sourced, not run directly)

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.

Optional: td integration

If the project uses td for in-flight agent work, the scripts detect it (PKH_TD=auto|on|off, default auto) and bridge one way. Git stays the source of truth. A td issue labelled pkh with the same title points at its TODO.md item, and TODO.md never stores td ids, which are machine-local.

• Starting an item: scripts/start-todo.sh --title "<substring>" creates or reuses the td issue and starts it.
• promote-todo.sh then prints a harvest-then-review hint and never closes the issue. todo-kanban.sh marks in-flight items and lists orphaned issues.
• init.sh appends a routing snippet to the agent contract when td is present.
• "Maybe later" still goes to add-todo.sh, not td create / td defer.

Without td, nothing changes. Layering, cross-machine caveats, the td exit plan, and GitHub Issues / Linear guidance are in references/integrating-trackers.md.

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
• assets/td-routing.md.template — td ↔ TODO.md routing snippet (appended by init.sh when td is detected)
• 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
• scripts/start-todo.sh — optional td bridge: start an item as a td issue
• scripts/_lib/todo-match.sh, scripts/_lib/td-bridge.sh — shared helpers

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