saidwhen

saidwhen

Your project's wiki, maintained by your agents — and actually trustworthy.

saidwhen is an agent-maintained project wiki in a loop with OpenSpec. One OKF bundle of plain markdown serves three readers at once: agents read it as project memory before every task, the spec workflow draws on it and feeds it, and humans browse it as a compiled wiki site. What makes it trustworthy is built-in provenance plumbing: every entry knows who said it, when, and what would reopen it — so agents can challenge stale knowledge instead of blindly obeying or silently ignoring it. No server, no database, no vector index, no SDK.

 spec requirement          decision                 attributed fact
┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│ "MUST use magic  │────▶│ chose magic links│────▶│ users are        │
│  link login"     │ why?│ over OAuth       │ who │ external, no IdP │
│                  │     │ because...       │said?│ —ivan, 2026-07-08│
└──────────────────┘     └──────────────────┘     └──────────────────┘

Six months later someone asks "can we add OAuth?" — the agent follows the links, finds it was rejected and why, and asks only: "decided 2026-07-08 because users have no IdP — is that still true?" No re-litigating, no re-interviewing, no blind obedience.

The loop

• In: exploring or proposing an OpenSpec change consults the wiki first and pulls the relevant facts, constraints, and decisions into the proposal — by link, not by re-asking you.
• Out: archiving a change writes the crystallized knowledge back and updates the architecture pages it altered — and an optional Stop hook makes it automatic, blocking only when the wiki has fallen behind an archive and staying silent (zero tokens) when it hasn't.
• Checked: the validator resolves every link, flags citations of superseded decisions, and maps a PR's changed files back to the decisions that govern them.
• Rendered: CI compiles the bundle into a browsable wiki site on every push (latest build → wiki-site artifact) — rich pages for humans, zero extra tokens for agents, regenerated instead of maintained. The output is plain static HTML: host it anywhere, or render the single-file wiki.html and open it from disk.

Quickstart (5 minutes)

1. Install the skills — one command:
   • Any agent (Claude Code, Cursor, Codex, 20+ others): npx skills add h4nz4/saidwhen
   • Claude Code (full suite as a plugin): /plugin marketplace add h4nz4/saidwhen then /plugin install saidwhen@saidwhen
   • Or copy directories from skills/ into your agent's skills folder — .claude/skills/ (Claude Code), .agents/skills/ (Codex), or your agent's equivalent (install matrix). Minimal set: wiki-init, wiki-explore, wiki-capture.
2. Ask your agent to set up the wiki — wiki-init scaffolds docs/knowledge/ and offers the AGENTS.md snippet, the ambient fallback for agents without Agent Skills support.
3. Work normally. Your agent now reads docs/knowledge/ before asking you anything, and records facts and decisions as they crystallize.

Optional: vendor validator/validate.py (one stdlib file) and run python validate.py docs/knowledge in CI — the wiki-capture skill also bundles it. OpenSpec user? Install the wiki-opsx-* skills — that's the loop above.

The trust layer measurably works

The wiki's integrity behaviors — recall instead of re-planning, the delta question instead of blind obedience, no fabricated citations — and the 2.0 wiki-first claims are backed by pre-registered experiments with published transcripts across five rounds, zero rubric exceptions.

Full write-up: evidence/VALIDATION.md. Honest limitations included (single model family, demo-sized wikis, unblinded scoring with published raw outputs; round 6 ran lean — 12 sessions at low reasoning effort — per a recorded owner directive, with all amendments registered before the first run).

And this repo runs on it

docs/knowledge/ is saidwhen's own live bundle, not a demo. Why is the product wiki-first now? The decision answers, linked to the owner interview that justified it — the same chain the diagram above promises you. CI validates the bundle, renders the site, and checks this README against the bundle for broken links and citations of superseded decisions, on every push. saidwhen itself is developed with OpenSpec through the wiki-opsx-* skills we ship: the loop you get is the one we use daily.

Docs that don't rot

Any in-repo markdown — architecture notes, docs/, even your AGENTS.md — can carry the same why-links as specs — like this real one: (why). Then

python validator/validate.py docs/knowledge --check-specs AGENTS.md --check-specs openspec/specs

fails CI when a link breaks or when a cited decision has been superseded: the doc leaning on a stale why gets flagged, with its successor named. Docs stop silently outliving the decisions under them.

The reverse direction works too: give a decision a scope: of the paths it governs, and

git diff --name-only main | python validator/validate.py docs/knowledge --check-diff -
WHY   decisions/eur-only.md (accepted) governs: index.html

tells a PR review — human or agent — which recorded decisions a change touches, before it quietly rebuilds something already rejected. Advisory output; it never fails the run.

What's in the box

How it's different from agent-memory tools

Memory tools capture everything ambiently (transcripts, embeddings) and hope retrieval finds the needle. saidwhen captures at the moment knowledge crystallizes — the point of highest signal — as attributed facts a human can browse on GitHub and an agent can cite by path. It is a format and a behavior, not a platform: produced without an SDK, consumed without an integration, portable between agents, and it degrades gracefully to well-organized docs.

License

MIT. Contributions welcome — see CONTRIBUTING.md, especially the rule about re-validating behavior edits.