intent — Managing What the Project Means to Do

This skill is the process; the mechanics live in the kb skill. Every command below is .claude/skills/kb/kb intent …. There is no separate implementation — see decision 0002 for why, and do not try to split them without reading it first.

.claude/skills/kb/kb intent list --open

The one distinction that matters

Intent is future-tense and has a lifecycle — what the project means to do. Capability is present-tense and is simply either true or stale — what the system does today. They are different documents in different bundles, and conflating them is what makes knowledge bases rot.

Releasing is where they meet: marking an Intent Released requires linking the Capability it produced. That single obligation is what stops the knowledge base falling behind the code.

Full glossary: kb/CONTEXT.md.

Lifecycle

Backlog ──▶ Refinement ──▶ InProgress ──▶ Released
   └──────────┴─────────────┴──────────▶ Cancelled / Superseded

State	Means	Owes
Backlog	Accepted as real work, not yet specified	—
Refinement	Being specified; the design is not settled	—
InProgress	Design settled, actively being built	—
Released	Shipped	A Capability link, for user-visible kinds
Cancelled	Decided against	A reason
Superseded	Replaced by another Intent	A successor

Transitions are not policed — work genuinely jumps stages, and a one-line fix may go Backlog straight to Released. What is enforced is what a record owes wherever it currently sits.

Deprecated is not a state. You deprecate a shipped Capability, not a backlog item. Retiring something is new Intent, of kind: deprecation, followed later by one of kind: removal.

Kinds

User-visible — these appear in release notes:

feature · bug · performance · security · deprecation · removal

Internal — these do not:

refactor · docs · test · build · spike

breaking: true is separate from kind, because a feature or a bug fix can break compatibility. It is what drives a major bump.

Only user-visible kinds must link a Capability on release. Internal work often has nothing for the knowledge base to learn, and inventing a document for "added three labels" is the noise this design avoids.

Working with it

Capture. GitHub Issues is the inbox — anyone may file there. An issue becomes Intent when a maintainer decides it is real work worth durable prose. Most issues never do.

.claude/skills/kb/kb intent new --title "…" --description "…" --kind feature --issue 1234

Then write the Problem section. Resist describing a solution there — the Feature Request template's Job Story form ("When [trigger], I want to [goal], so I can [outcome]") is a good discipline.

Progress.

.claude/skills/kb/kb intent refine 0007

.claude/skills/kb/kb intent start 0007

Finish. Each verb demands what its state owes, at the moment you have the answer:

.claude/skills/kb/kb intent release 0007 --capability morphir/morphir-scala:/wasm-linking.md --artifact pkg:maven/org.finos.morphir/morphir-langkit@0.4.0

.claude/skills/kb/kb intent cancel 0007 --reason "…"

.claude/skills/kb/kb intent supersede 0007 --by 0012

After any change, regenerate the index and the database:

.claude/skills/kb/kb refresh

Asking questions

.claude/skills/kb/kb intent list --open

.claude/skills/kb/kb intent list --user-visible --state Released

Anything more involved goes through SQL against the v_intent view:

.claude/skills/kb/kb query --sql "SELECT state, kind, count(*) FROM v_intent GROUP BY 1,2 ORDER BY 3 DESC"

Keeping it honest

.claude/skills/kb/kb intent check

Errors are unmet obligations — a Released record with no Capability, a Cancelled one with no reason, a superseded_by naming nothing. Warnings are staleness: an Intent sitting in Refinement or InProgress past the bundle's stale_after_days is the honest signal that nobody is working on it. Move it on, or move it back to Backlog and say so.

Backlog is deliberately never stale. A backlog is meant to sit.

Portability

Nothing is hardcoded. The intent bundle is the one whose index.md frontmatter carries intent: true, and its settings live there too:

intent: true
system: pkg:maven/org.finos.morphir/morphir-core
capability_bundle: morphir/morphir-scala
stale_after_days: 60

system and released artifacts are Package URLs — a global vocabulary, so the same skill works in a Python or npm repository unchanged. Capability links use bundle-label:/path.md instead, because a Capability is a document in this knowledge base, not a registry-backed package. decision 0003 records why both exist.

In a repository with no intent bundle yet:

.claude/skills/kb/kb intent init --system pkg:pypi/example --capability-bundle example