Cheatsheet

One page. Daily use. Bookmark it.

Install / update

# Fresh install
curl -fsSL https://raw.githubusercontent.com/kostiantyn-matsebora/ginee/main/install.sh | bash -s -- --adapter claude
.\install.ps1 -Adapter claude        # PowerShell

# Pin version
./install.sh --ref v0.1.0 --adapter claude
$env:GINEE_REF='v0.1.0'; iwr ... | iex

# Update (preserves local/) — installer is NOT co-located (D27); use /ginee-update or the bootstrap one-liner:
GINEE_UPDATE_ONLY=1 GINEE_ADAPTER=claude bash -c "$(curl -fsSL https://raw.githubusercontent.com/kostiantyn-matsebora/ginee/main/install.sh)"
$env:GINEE_UPDATE_ONLY='1'; $env:GINEE_ADAPTER='claude'; iwr -useb https://raw.githubusercontent.com/kostiantyn-matsebora/ginee/main/install.ps1 | iex

Adapters: claude · copilot-cli · agents-md · generic.

First-day workflow

Run initial discovery                  # ginee-discovery skill

Then:

@<role> <task>                         # dispatch a specialist
auto: <task>                           # elide per-phase gates (D12)
branch: <task>                         # force feature-branch + PR mode (D17)
wt: <task>                             # working-tree only — no commits
commit: <task>                         # commit-no-push
auto: branch: <task>                   # combine — auto mode + branch+PR

Framework skills (tier-1: Claude Code, Copilot CLI)

Slash commands /ginee-<skill> [args]. Natural-language phrasings also match. Tier-2/3 fallback: act as team-lead and ….

/ginee-discovery                          # initial onboarding (Step 2 of install)
/ginee-rediscover                         # full re-discovery + re-extraction
/ginee-file-bug <title>                   # opens issue in primary repo (current)
/ginee-file-feature <title>
/ginee-file-framework-bug <title>         # opens issue in ginee upstream repo
/ginee-file-framework-feature <title>
/ginee-pick-up #<N>                       # GitHub issue (primary repo)
/ginee-pick-up <todo-ref>                 # TODO line (path:line / "TODO about X")
/ginee-pick-up <freeform-description>     # direct instruction
/ginee-triage                             # list ready issues + TODOs
/ginee-triage framework                   # list ready framework upstream issues
/ginee-promote-discussion #<N>            # discussion → draft issue
/ginee-reindex                            # reconcile index with current repo state (whole repo)
/ginee-reindex <file|class>               # scoped reconciliation
/ginee-update                             # update framework to latest release (preserves local/)
/ginee-update <tag|branch|sha>            # update to a named ref
/ginee-address-review #<PR>               # ingest review comments on an open PR (D24)
/ginee-iterate                            # relay review-cycle reply to warm cardinal — auto-engages on warm registry + in-flight reply; also "iterate on @<role>" / "forward to the warm cardinal"

Compliance — Bash hook (T3)

adapters/claude/hooks/pre-tool-use-bash.{ps1,sh} blocks 4 shell-command patterns at the tool-call layer:

Opt out: local/framework.config.yaml § compliance.disabled: [pretooluse-bash-hook]. Full spec: migrations/pretooluse-bash-hook.md.

Freeform requests (any tier)

Use ginee to <task description>           # team self-dispatches; no skill needed

Compliance statusline (T4)

adapters/claude/statusline.{ps1,sh} emits a single line (≤ 100 chars) to Claude Code’s status row showing [ginee] #<N> · phase: ? · warm: ? · trailer: <ok|needed> · cap: <N>%. Trailer / cap fields are locally-derived; phase + warm are placeholders pending D43 plumbing.

Wire via .claude/settings.json § statusLine. Opt out: local/framework.config.yaml § compliance.disabled: [compliance-statusline]. Full spec: migrations/compliance-statusline.md.

Phase lifecycle

Compliance — cardinal tools whitelist

Each pointer subagent ships with a scoped tools: list — solution-architect has no Edit / Write (Class A hard gate); ai-engineer has no Bash. Other cardinals retain full tool sets; path / command scope enforced by T2 / T3 PreToolUse hooks (parent: #135).

# local/framework.config.yaml — opt out per tactic
compliance:
  disabled:
    - subagent-tools-whitelist   # restore unscoped tools on all cardinals

Full spec: migrations/cardinal-tools-whitelist.md.

GitHub label scheme

Compliance — PreToolUse Edit/Write hook (T2)

Cross-platform hook at adapters/claude/hooks/pre-tool-use-edit.{ps1,sh} blocks Edit / Write / MultiEdit on:

Wire into .claude/settings.json per adapters/claude/install.md § Compliance hooks. Bypass per call: SKIP_GINEE_COMPLIANCE=1. Opt out: local/framework.config.yaml § compliance.disabled: [pretooluse-edit-hook]. Full spec: migrations/pretooluse-edit-hook.md.

Compliance — Tier 2 hooks (T5 / T6 / T7 / T8)

Four further hooks layer prompt-time / action-time / turn-time enforcement (parent: #135). All wire automatically via /ginee-update.

Opt-out tactic-ids: user-prompt-submit-hook · posttooluse-edit-hook · stop-hook · pretooluse-send-message-hook. Full specs: migrations/user-prompt-submit-hook.md · migrations/posttooluse-edit-hook.md · migrations/stop-hook.md · migrations/carry-forward-injection.md.

Compliance — Tier 3 closeout (T9 / T10 / T11 / T12 / T13)

Last batch of the maximum-force Claude playbook (parent: #135).

# local/framework.config.yaml — Tier 3 per-tactic opt-outs
compliance:
  disabled:
    - slash-commands
    - main-thread-permissions
    - session-start-hook
    - optimized-by-attestation
# Warm registry soft cap — over-cap forces fresh + summary handoff per warm-cardinal-default.md
warm-reuse:
  dispatch-cap: 15

Slash commands install via install.{ps1,sh} (re-run via /ginee-update). All five tactics fail-open on error. Full specs: migrations/claude-md-bookending.md · migrations/slash-commands-suite.md · migrations/warm-cardinal-default.md · migrations/session-start-hook.md · migrations/optimized-by-attestation.md.

Sub-issue dispatch (D39)

On issue-sourced tasks, team-lead creates one GitHub sub-issue per cardinal dispatch under the parent — labelled by role + phase, threading progress comments + cumulative time, closed on phase-report return. Cross-session resume reads parent + open sub-issues; no transcript replay.

notrack: <task>                    # opt out of sub-issue tracking for this task

Per-issue opt-out — apply ginee:track:off label on the parent issue.

Repo-wide opt-out — local/framework.config.yaml:

dispatch:
  tracking: in-context             # sub-issues (default on github.repo) | in-context
  time-tracking: false             # turn off the time-tracking surface

Assignee precedence — non-empty human assignee on a sub-issue overrules the ginee:role:<cardinal> label; cardinal dispatch suspended until cleared. Reassign to empty to resume.

Progress-comment shape (cardinal-authored on the sub-issue):

Started: <sub-task>. time: 0m. cumulative: 12m.
Done: <sub-task>. <commit-link>. time: 18m. cumulative: 30m.

Phase-report return doubles as the closing comment; mandatory ## Time spent: <H>h <M>m perceived effort; <N> progress comments on sub-issue #<M>.

Triage scoring (D23)

score = value / complexity                # H=3, M=2, L=1 (ATAM H/M/L)

/ginee-triage sort key: Score DESC, Age DESC. Unscored grouped at bottom. TODO marker ☐ [v:H c:L] Description (case-insensitive). Sticky <!-- ginee:score v=1 --> comment per issue; refresh via @team-lead recompute score #<N>. Override formula: local/framework.config.yaml § triage.scoring-formula.

Classical-architect SA model (D25, refined #182)

SA has three activities, all OUTSIDE the implementation phases (Phase 4 / 5 / 6):

Phase 4 / 5 / 6 — categorical refusal. SA is NOT dispatched during implementation phases. Engineer-surfaced architectural-delta needs route through team-lead’s gate → user picks defer to next design cycle OR stop + re-enter Phase 1–2.

D25 doc-ownership map (per core/protocols/doc-roles.md):

Implementation rendering — forbidden in every SA artefact (#182): adopter function / member identifiers · line-numbered citations into the working tree · commit SHAs · handler-body snippets · “how to wire it” prescriptions. ADRs cite mechanisms + rationale, not code sites. SA’s ## Verification log carries SA-artefact content self-lint: PASS / <N findings> per touched artefact.

Engineer-proposed architectural change (delta to contract / topology / stack / NFR-affecting): flag in ## Open issues + ## Next dispatch needed: team-lead · architectural-delta gate · <reason>. Team-lead surfaces user gate. SA dispatched at Phase 1–2 only if user picks stop + re-enter. Local bug fixes (no architectural delta) route engineer → engineer.

Greenfield vs delta — discovery detects “no architecture doc” → greenfield: true in local/project-profile.md → SA enters greenfield design on first non-trivial task. Delta mode produces ADR + ASR amendments; never rewrites the architecture doc wholesale.

Migration on upgrade: @team-lead rediscover runs Step 8c re-attribution sweep per migrations/classical-architect.md.

Change governance (D45)

Pre-authorship gate on CR / ADR drafting. Adopter-controlled via local/framework.config.yaml § change-governance.

change-governance:
  cr:
    enabled: true                       # set false → skip CR authorship
    skip-when-issue-source: true        # issue IS the requirement record
  adr:
    enabled: true                       # set false → skip ADR authorship
    require-architectural-delta: true   # no delta heuristic → skip ADR
  prompt-before-create: non-trivial     # always | never | non-trivial

Combine with auto: · branch: · wt: · commit: · model:<tier> · notrack:.

Architectural-delta triggers (ADR gate) — component boundaries · wire contracts · NFR-bearing claims · architecture invariants · stack / topology / infrastructure.

Non-trivial heuristic — ≥ 2 delta triggers OR local/requirements.md register-diff non-empty.

Skip-reason enum — config-disabled · issue-source-skip (CR) · no-architectural-delta (ADR) · prefix-override · user-declined. Logged under ## Decisions made in the phase-report.

Full spec: migrations/change-governance-opt-out.md.

Address review on a PR (D24)

/ginee-address-review #<PR>               # ingest review comments + reviews
@team-lead address-review #<PR>           # command equivalent (every adapter)

Procedure: fetch pulls/{N}/comments + /reviews → dedup by thread-id (skip resolved + already-marked) → route each remark per local/bindings.md § Source-of-truth ownership → surface plan table for approval (forced-interactive, even in auto:) → dispatch specialists in parallel → squash fixes into one cycle commit + push → post per-thread replies + one sticky cycle summary. Lossless coverage (every remark → fix OR reply). Markers <!-- ginee:review-reply r=<id> --> (per-thread) + <!-- ginee:review-cycle n=<N> --> (sticky).

Subagent-return schema (D29)

Every cardinal-dispatch return is schema-bound per core/templates/phase-report.md. Dispatch payloads · sticky ginee:score · audit comments · sub-issue bodies · review-cycle comments follow sister sidecars under core/protocols/*-schema.md (D49).

Status: Done | In-progress | Blocked | Hand-off

## Estimate               # table — sub-task · estimate (min)   (required iff dispatch carried ## Scope size ∈ {15-60m, >60m}; placed BEFORE ## Files touched; #168)
## Files touched           # table — path · Δ lines · purpose       (required; (none) if empty)
## Decisions made          # bullets — imperative + cite (≤ 80 ch)  (required; (none) if empty)
## Verification log        # table — command · outcome              (required)
## Open issues             # bullets — issue + owner (≤ 80 ch)      (required; (none) if empty)
## Next dispatch needed    # one-liner — role · surface · reason    (required; (none) if empty)
## Source reads (this dispatch)  # table — path · justification · index entry  (required; (none) if empty)
## Hand-off                # core/templates/hand-off-note.md         (forced-handoff only)
## Stop-state              # Done / In-progress / Not-started        (Status: In-progress only)
## Notes                   # free prose · ≤ 200 words                (optional escape hatch)

8 mandatory checks before report-as-done — 6 from D22 / D26 / D48 (D48 added RFC 2119 binding-strength signal) + no narrative preamble + ## Estimate present iff dispatch carried ## Scope size ∈ {15-60m, >60m} (#168). Forbidden — narrative preamble · restated dispatch context · code snippets outside the Notes carve-out · verbose rationale outside ## Notes · parenthetical comma-soup. Target reduction vs free-form returns: ~70%.

Scope-size classifier (#168). Team-lead emits ≤15m · 15-60m · >60m + one-line signal before every cardinal dispatch — written into the dispatch-prompt’s ## Scope size section and the sub-issue’s **Scope size:** field. 15-60m / >60m load iteration-protocol + require the cardinal’s ## Estimate return. ≤15m skips both — class is recorded explicitly. lite: prefix auto-classifies as ≤15m. Full spec — migrations/estimation-gate-fires.md.

Index-first read order — cardinals consult local/index/ summaries first; raw source reads are fallback + require a one-line justification in ## Source reads. Orchestrator’s single format-only re-dispatch carve-out fires when raw source appears in ## Files touched AND ## Source reads is missing / (none). Bedrock: core/protocols/index-protocol.md § Read order.

Hot-spec frontmatter (D47)

Every core/ hot-spec file (process.md · process/*.md · protocols/*.md · roles/*.md · roles/*.details.md) carries a YAML header declaring its load contract:

---
audience: <role | all-cardinals | team-lead-only>
load: always | on-demand
triggers: [keyword1, keyword2]                # required when load == on-demand
cap-bytes: <N>                                # per-file byte budget
reads-before-applying: [path1, path2]         # [] if none
---

Excluded — core/templates/*.md · core/skills/ginee-*/SKILL.md · local/roles/*.md. Validator — scripts/context-economy-check.ps1 fails CI on missing frontmatter; Optimized-By: ai-engineer trailer bypasses. Failure codes — missing · malformed · missing-key · invalid-load · empty-triggers · invalid-cap-bytes.

Full spec: core/protocols/hot-spec-format.md.

Release-surface authoring (D40)

Three surfaces, three voices, three caps — applies only to maintainers drafting release artefacts.

Sidecar self-lint — 5 checks before publish: word cap · user-value voice · (D<N>) tag · no implementation boilerplate · migration link in footer.

Pattern — lead with adopter verb (/ginee-update works again not Step 1 no longer requires installer scripts inside .agents/ginee/). Full spec: core/protocols/changelog-protocol.md.

Blueprint-diff gate (D41)

Phase 4 entry precondition — every dispatch touching local/framework.config.yaml § visual-source-of-truth.path diffs vs blueprint-ref first, classifies deltas, surfaces to team-lead before edits.

# local/framework.config.yaml — defaults derive from `mockup:` when block absent
visual-source-of-truth:
  type: html-mockup           # html-mockup | figma | image | video | other
  path: docs/mockup.html
  blueprint-ref: origin/main  # or v1.2.0, snapshot path, Figma version URL
  scope-discriminator: block-glob
  enabled: true

4 mandatory checks before edits begin — config resolved · diff computed · classification complete · ## Verification log row written. Inapplicable case (no edit on configured path) — cite "visual-SoT untouched — protocol n/a" and skip.

Full spec: core/protocols/blueprint-diff-protocol.md.

Option-list shape (D30)

Every Phase 2 design proposal + every iteration-protocol Propose step (Phase 4–7 > 15-min sub-tasks with a live adopt-vs-build axis) MUST surface ≥ 1 adopt candidate OR an explicit (none viable — <reason>) cite.

Options:
- adopt — <name> v<version> — <license> — <source link>
  — fit: <one-line concrete rationale, citing constraint / NFR / stack>
- adopt — <name> v<version> — <license> — <source link>
  — fit: <one-line>
- build — <scope> — rationale: <why surveyed adopts rejected>
# OR if research empty:
- (none viable — <one-line reason>)
- build — <scope> — see ADR draft.

5 mandatory checks before surfacing — adopt floor present · citations complete (name · version · source · license · fit) · tagging explicit (adopt / build / hybrid — no silent mixing) · empty research documented · fit rationale concrete (not hand-waved). Self-lint runs in-thread; no external linter. License gating — framework expresses no opinion; adopters wire policy in local/. Inapplicable sub-tasks cite *“axis n/a — "* and skip.

Full spec: core/protocols/options-protocol.md. Example: core/protocols/doc-authoring-examples.md § 11.

Model tier (D31)

Three tiers (vendor-neutral); per-task prefix combinable with auto: / branch: / wt: / commit::

reasoning  ← team-lead · solution-architect           (Claude default: claude-opus-4-7)
standard   ← ai-engineer · 4 engineer cardinals       (Claude default: claude-sonnet-4-6)
fast       ← opt-in for mechanical work                (Claude default: claude-haiku-4-5-20251001)

Per-task prefix examples:

model:reasoning Add the new ASR utility-tree leaves for the latency NFR.
auto: model:fast Re-label stale issues with ginee:blocked.
branch: model:reasoning Pick up #N

Resolution order (stop at first match) — (1) model:<tier> prefix · (2) Phase-3 user answer · (3) local/framework.config.yaml § model-tier.per-role.<role> · (4) core/roles/<role>.md default-tier:.

Adapter override. Edit local/framework.config.yaml § model-tier (per-role tier + per-adapter tier→model map); re-run installer to apply.

Full spec: migrations/model-tier.md.

Source-of-truth pattern

local/index/*               ← default read every dispatch
docs/* (raw)                ← on demand only (verbatim wording matters)
local/bindings.md           ← governance + tie-breakers
local/project-profile.md    ← discovered project context
local/framework.config.yaml ← concept → path mappings

Strict-domain rule (forbidden role-crossings)

Per local/bindings.md § Project role boundaries. Each row is a hard stop.

Cross-domain need surfaced mid-task → propose hand-off in final report. Never patch across. Engineer-proposed architectural changes (D25) route to solution-architect § Review (APPROVE / REJECT / REQUEST-CHANGES).

Index file Load-when tiers

Per cardinal role kernel ## Source of truth:

• always — foundational; loaded every dispatch (single-digit KB combined).
• scope-loaded — trigger phrase (e.g. wire/endpoint touch, infra work, dep bump, test authoring). Loaded only when the task description matches.

Specialist reports loaded set in first response.

Iteration protocol (work > 15 min)

1. Estimation-first dispatch — task decomposition + per-task minutes before edits.
2. User approves the batch.
3. 3–5 min iterations, each stoppable.
4. Stop anywhere → resume next session with zero rework.

Delivery modes (D17)

Framework defaults: branch for issue / TODO-sourced; wt for freeform. Auto-mode default: wt.

Common pitfalls

Where things live

.agents/ginee/
├── core/                       # upstream — process spec + role kernels + templates
│   ├── process.md              # common — principles · doc style · reporting · index (D35)
│   ├── process/                # D35 — phase + dispatch files, load-on-demand per role
│   │   ├── phase-{1..8}-*.md   #   one file per lifecycle phase
│   │   └── dispatch.md         #   orchestration — skill-runner · parallelism · auto mode
│   ├── protocols/              # load-on-demand protocol specs (D46 — all named workflows here)
│   │   ├── automatic-mode.md             # D12 auto-mode
│   │   ├── delivery-modes.md             # D17 branch / wt / commit
│   │   ├── ci-watch.md                   # D20 post-PR CI watch
│   │   ├── triage-scoring.md             # D23 value × complexity
│   │   ├── doc-authoring-protocol.md     # D22 / D26 / D29 enforcement
│   │   ├── doc-authoring-examples.md     # paired bad/good examples
│   │   ├── doc-roles.md                  # D25 all-roles authorship
│   │   ├── doc-size-caps.md              # D44 per-class size caps
│   │   ├── index-protocol.md             # local/index/ extraction + load triggers
│   │   ├── index-syntax.md               # .idx DSL grammar
│   │   ├── iteration-protocol.md         # estimation-first dispatch
│   │   ├── options-protocol.md           # D30 adopt-vs-build shape
│   │   ├── blueprint-diff-protocol.md    # D41 visual-SoT diff gate
│   │   ├── changelog-protocol.md         # D40 release-surface authoring
│   │   ├── github-integration.md         # issue / PR / label flow
│   │   ├── cross-agent-handoff.md        # structured hand-off
│   │   ├── cross-domain-bugs.md          # propose → implement → verify
│   │   └── post-task-check-in.md         # after every completed request
│   ├── roles/                  # 7 cardinal role kernels (each declares phase-participation:)
│   └── templates/              # bindings, PR description, hand-off note,
│                               # requirements-register (D25), asr-utility-tree (D25)
├── adapters/<client>/          # upstream — per-client renderings (pointer files)
├── extras/roles/               # upstream — opt-in specialists
└── local/                      # YOU OWN THIS — survives every update
    ├── project-profile.md
    ├── bindings.md
    ├── framework.config.yaml
    ├── requirements.md         # D25 — FRs / NFRs / Constraints (SA-authored)
    ├── asr-utility-tree.md     # D25 — ASRs derived via ATAM (SA-authored)
    ├── index/                  # extracted summaries
    └── roles/                  # your custom roles