The Tag System

CAP Pro has two mandatory tags. That's it.

// @cap-feature(feature:F-Hub-Spotlight, ac:1) Render slides as horizontal carousel
// @cap-todo(ac:F-Hub-Spotlight/AC-3, risk:medium) Reduced-motion fallback missing

Everything else — risk levels, decisions, history, hotspots — is either an optional subtype of these two, or auto-generated by the tag scanner.

The two primary tags

@cap-feature — what does this code do?

Marks code that implements a Feature Map AC.

// @cap-feature(feature:<id>, ac:<n>) <one-line description>

• feature: — the Feature Map ID, e.g. F-Hub-Spotlight
• ac: — the AC number this code satisfies, e.g. 1, 2, 3
• description — one line

Multiple @cap-feature tags on the same code block are allowed (one piece of code can satisfy multiple ACs).

@cap-todo — what's still open?

Marks open work that the agent or the next developer needs to address.

// @cap-todo(ac:<feature>/<ac>) <one-line description>
// @cap-todo(ac:<feature>/<ac>, risk:<low|medium|high>) <one-line description>
// @cap-todo(decision:<topic>) <one-line description>

Subtypes:

• risk:low|medium|high — surfaces in /cap:scan and cap-curator MODE: STATUS reports
• decision:<topic> — flags an open architectural decision; /cap:scan lists these for review

Optional tags

These appear automatically from /cap:scan and cap-historian runs — you don't usually write them by hand:

Tag	Purpose
@cap-history(sessions:N, edits:M, since:DATE)	Hotspot marker — added by the curator for frequently changed files
@cap-decision(learned:DATE)	Architectural decision recorded from a session
@cap-pitfall(learned:DATE)	Gotcha learned from a session
`@cap-risk(level:low	medium

Why so few tags?

Most engineering frameworks have 8–15 mandatory annotations: @author, @since, @deprecated, @throws, @param, @returns, @see, @example, @todo, @fixme, @xxx, @hack, @bug, @review, …

In practice, devs maintain maybe three of them, and the rest become noise. CAP Pro picks the two that pull their weight for code-first planning:

• @cap-feature ties code to a Feature Map AC — answers "what does this do, why does it exist?"
• @cap-todo ties open work to a Feature Map AC — answers "what's left?"

Everything else — what it returns, who wrote it, when it changed — your IDE, git, and TypeScript already tell you. Don't duplicate that information in comments.

Tag scanner

/cap:scan walks the repo, extracts all @cap-* tags using a regex with dotAll flag (works for any language with // ... or /* ... */ style comments), and:

1. Refreshes Feature Map entries with the current set of @cap-feature tags per AC
2. Lists open @cap-todo tags grouped by feature, sorted by risk
3. Flags orphaned tags (point to a feature ID that doesn't exist)
4. Detects ACs that have no @cap-feature tag (un-implemented)

Output is both human-readable (terminal) and machine-readable (re-written into FEATURE-MAP.md).

Multi-runtime support

The tag system is language-agnostic. The scanner uses a regex, not an AST, so it works across:

• TypeScript / JavaScript (// @cap-feature)
• Python (# @cap-feature)
• Go (// @cap-feature)
• Rust (// @cap-feature)
• HTML (<!-- @cap-feature -->)
• CSS / SCSS (/* @cap-feature */)
• Markdown (<!-- @cap-feature -->)

If your language uses any of //, #, /* */, <!-- -->, the scanner finds tags.

Honest signal, not vibe-coding decoration

A common failure mode in AI-assisted coding is "decorative comments" — the AI adds // This function calculates the total above function calculateTotal(), which adds no information. CAP Pro's tag system is the opposite:

• @cap-feature adds traceability — links code to product spec
• @cap-todo adds honesty — surfaces what isn't done yet

Neither tag describes what the code does (the code does that). Both tags describe what it MEANS in the context of the project plan.