Spec Kitty

└─ kitty-specs
   └─ Charter Pack Activation Layer

Mission Run:

📚 Docs ↗

Contracts

charter-activate-cli.md

Contract: charter activate

Command: spec-kitty charter activate <kind> <id> [--cascade <scope>]

Synopsis

Adds an artifact to the project's activated set for its kind. Once at least one artifact of a kind is explicitly activated, only activated artifacts of that kind are available (hard restriction). When no activation entry exists for a kind, all built-in artifacts remain available (backward-compat fallback).

Arguments

Argument	Type	Required	Description
`kind`	ActivationKind	Yes	One of: `mission-type`, `directive`, `tactic`, `styleguide`, `toolguide`, `paradigm`, `procedure`, `agent-profile`, `mission-step-contract`
`id`	string	Yes	Artifact ID as it appears in doctrine (e.g., `python-style-guide`, `software-dev`)
`--cascade`	string	No	Cascade scope: `all`, or one or more comma-separated CLI kind names (hyphen form: `directive`, `tactic`, `styleguide`, `toolguide`, `paradigm`, `procedure`, `agent-profile`, `mission-step-contract`). Default: no cascade.

Behavior

1. Validate kind is one of the 9 activatable kinds. Error if unknown. 2. Validate id exists in the doctrine catalog for that kind. Error if unknown artifact. 3. Read current activation state from .kittify/config.yaml. 4. If activated_<kind> key is absent in config.yaml (pre-upgrade project): materialize the initial activation set from src/charter/packs/default.yaml for that kind before adding id. If the live doctrine catalog for this kind has entries absent from default.yaml (third-party artifacts), emit a visible warning that those artifacts will not be included in the materialized set. 5. Add id to the activation set for kind in config.yaml. 6. If --cascade is absent: emit a warning listing cross-kind references from id that were NOT cascaded, with hint to use --cascade. 7. If --cascade <scope> is present: activate all artifacts of the specified kinds that id references (DRG edges or catalog cross-references). 8. Write updated activation state to .kittify/config.yaml (ruamel.yaml round-trip, comment-preserving). 9. Print confirmation: which artifact was activated, which were cascade-activated (if any), which cross-references were skipped (if cascade was partial).

Exit Codes

Code	Meaning
0	Activation successful
1	Unknown kind or unknown artifact ID
2	config.yaml write error

Output (human-readable)

Activated: directive/python-style-guide
Cross-references not cascaded (use --cascade tactic to include):
  - tactic/test-driven-development
  - tactic/clean-arch
Hint: spec-kitty charter activate directive python-style-guide --cascade tactic

With --cascade tactic:

Activated: directive/python-style-guide
Cascade-activated (tactic): test-driven-development, clean-arch

State Written (config.yaml)

activated_directives:
  - python-style-guide
activated_tactics:           # only if --cascade tactic was used
  - test-driven-development
  - clean-arch

charter-deactivate-cli.md

Contract: charter deactivate

Command: spec-kitty charter deactivate <kind> <id> [--cascade <scope>]

Synopsis

Removes an artifact from the project's activated set for its kind. This is a first-class command, symmetric with charter activate. Deactivation with cascade only removes artifacts of the cascaded kinds that are exclusively referenced by the deactivated artifact — shared artifacts are preserved and warned about.

Arguments

Argument	Type	Required	Description
`kind`	ActivationKind	Yes	One of: `mission-type`, `directive`, `tactic`, `styleguide`, `toolguide`, `paradigm`, `procedure`, `agent-profile`, `mission-step-contract`
`id`	string	Yes	Artifact ID to deactivate
`--cascade`	string	No	Cascade scope: `all`, or one or more comma-separated CLI kind names (hyphen form: `directive`, `tactic`, `styleguide`, `toolguide`, `paradigm`, `procedure`, `agent-profile`, `mission-step-contract`). Default: no cascade.

Behavior

1. Validate kind and id. 2. Read current activation state from .kittify/config.yaml. 3. If the activation field for kind is absent (no explicit activation set): exit 1 with message "Kind '<kind>' has no explicit activation set. Run 'spec-kitty upgrade' to initialize the default pack before modifying individual activations." Do NOT implicitly materialize. 4. Remove id from the activation set for kind. 5. If --cascade is absent: emit a warning listing cross-kind references from id that were NOT evaluated for cascade deactivation. 6. If --cascade <scope> is present:

7. Write updated activation state to .kittify/config.yaml. 8. Print confirmation: deactivated artifacts, skipped shared artifacts, cascade warnings.

For each artifact of the cascade kinds referenced by id:
If it is referenced by at least one OTHER currently-activated artifact: skip it, emit "Shared — not deactivated: <kind>/<id>"
If it is exclusively referenced by id: deactivate it.

Shared Artifact Protection

An artifact is considered "shared" if any other activated artifact (of any kind) references it in its cross-kind edges. Shared artifacts are NEVER silently deactivated — they are skipped and reported. The user must explicitly deactivate shared artifacts if intended.

Exit Codes

Code	Meaning
0	Deactivation successful
1	Unknown kind; artifact ID not found in doctrine; artifact not in activated set; or kind has no explicit activation set (run `spec-kitty upgrade` first)
2	config.yaml write error

Output (human-readable)

Deactivated: directive/python-style-guide
Shared artifacts not deactivated (still referenced by other activated artifacts):
  - tactic/test-driven-development (referenced by: directive/clean-code)
Cross-references not evaluated (use --cascade tactic to check):
  - tactic/clean-arch

With --cascade tactic:

Deactivated: directive/python-style-guide
Cascade-deactivated (tactic): clean-arch
Shared (skipped): test-driven-development (still referenced by directive/clean-code)

State Written (config.yaml)

activated_directives:        # python-style-guide removed
  - clean-code
activated_tactics:           # only if --cascade tactic removed something
  - test-driven-development  # preserved (shared)
  # clean-arch removed

charter-list-cli.md

Contract: charter list

Command: spec-kitty charter list [--show-available]

Synopsis

Displays the project's current activation state, grouped by artifact kind. With --show-available, shows both activated artifacts and all available artifacts from doctrine side-by-side.

Arguments

Argument	Type	Required	Description
`--show-available`	flag	No	Also show all doctrine-available artifacts for each kind

Behavior

1. Read current activation state from .kittify/config.yaml via PackContext.from_config(). 2. For each of the 9 activatable kinds:

3. If --show-available: also query the doctrine catalog for each kind and display available (but not activated) artifacts indented below the activated section. 4. Output as a structured Rich table or panel — one section per kind.

If the kind key is absent from config.yaml: display "All built-ins (default)" — no explicit activation set.
If the kind key is present and non-empty: display the activated IDs.
If the kind key is present and empty: display "Nothing activated (explicit restriction)".

Output (human-readable, without --show-available)

Charter Activation State
━━━━━━━━━━━━━━━━━━━━━━━━━━
mission-type          software-dev, research
directive             python-style-guide, clean-code
tactic                (All built-ins — no explicit activation)
styleguide            (All built-ins — no explicit activation)
toolguide             (All built-ins — no explicit activation)
paradigm              domain-driven-design
procedure             (All built-ins — no explicit activation)
agent-profile         python-pedro, reviewer-renata
mission-step-contract (All built-ins — no explicit activation)

Output (with --show-available)

Charter Activation State (+ Available)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
directive
  ✓ python-style-guide    [activated]
  ✓ clean-code            [activated]
  ○ java-style-guide      [available, not activated]
  ○ go-style-guide        [available, not activated]

Exit Codes

Code	Meaning
0	Success
1	config.yaml read error or doctrine unavailable

charter-pack-consistency-check-cli.md

Contract: charter pack consistency-check

Command: spec-kitty charter pack consistency-check

Synopsis

Validates that the project's current charter activation state is coherent: all activated artifact IDs exist in doctrine, no unknown references, and the built-in spec-kitty doctrine pack is the default baseline. Returns structured output and a non-zero exit code if incoherence is found.

Arguments

None (reads from .kittify/config.yaml and the local doctrine catalog).

Behavior

1. Load current PackContext from .kittify/config.yaml. 2. For each kind with an explicit activation set (non-None):

3. Check cross-kind references: for each activated artifact that has DRG edges to other kinds, verify those referenced artifacts are also activated (or that the referenced kind has no explicit restriction — None means all available). 4. Report:

Query doctrine catalog for that kind's available artifact IDs.
For each activated ID: check it exists in doctrine. Collect unknowns.
Check no duplicate IDs in activation set.
coherent: true/false
unknown_references: IDs in activation set not present in doctrine
missing_from_doctrine: IDs referenced via DRG edges that are not in doctrine at all
kind_violations: IDs activated under the wrong kind
suggestions: human-readable resolution guidance per incoherence

Output (JSON, --json flag)

{
  "coherent": false,
  "unknown_references": ["directive/old-deprecated-guide"],
  "missing_from_doctrine": [],
  "kind_violations": [],
  "suggestions": [
    "directive/old-deprecated-guide: Not found in doctrine. Run 'charter deactivate directive old-deprecated-guide' to remove."
  ]
}

Output (human-readable)

Charter Pack Consistency Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✗ INCOHERENT

Issues found:
  directive/old-deprecated-guide — not found in doctrine
    → Run: spec-kitty charter deactivate directive old-deprecated-guide

Run 'spec-kitty charter list --show-available' to see current activation state.

On success:

Charter Pack Consistency Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ COHERENT — All activated artifacts are present in doctrine.

Exit Codes

Code	Meaning
0	Coherent — all checks pass
1	Incoherent — one or more unknown references or violations found
2	config.yaml read error or doctrine unavailable