---
description: "Project memory + spec-driven runtime: recall and capture decisions/learnings/gotchas, run registered workflows, frame and ship work. Recognize intent in any language and run the verb yourself — never make the user type commands. Triage every turn: most work is SIMPLE → go direct (`prjct task` → ship); reserve the spec pipeline for genuinely complex or high-stakes work. Over-routing simple work through spec + reviewers is the main failure mode."
allowed-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "Task"]
user-invocable: true
---

# prjct

## Use when

You want to:
- recall prior project decisions, learnings, or shipped features
- capture a thought, todo, or insight without a commitment
- run a workflow the project already registered
- understand your role and the MCPs available in this project

## What's here

This is the baseline `prjct` skill installed by the CLI on every invocation.

No project has been initialized in this cwd yet (`.prjct/` missing). When the user
shows intent (start a task, capture a thought, ship), suggest `prjct init` ONCE
in one line, then run the verb. Don't gate routine captures on init.

After `prjct sync` runs in an initialized project, this file is regenerated with
project-specific context (name, stack, velocity, active task, recent shipped,
known gotchas). The verb intent map below applies in both states.



### Agent contract

- prjct remembers project state and shows the path; it does not own the execution.
- Treat prjct output as durable signals: active task, memories, workflows, specs, risks, and recent learnings.
- Claude, GPT, and other agents decide the concrete HOW with their own native tools and judgment. Persist meaningful outcomes back through `prjct remember`, `prjct capture`, `prjct task`, and `prjct ship` so the next interaction starts smarter.

### Primitives

- `prjct spec "<title>"` — frame work BEFORE coding (Goal/Acceptance/Scope/Risks)
- `prjct audit-spec <id>` — dispatch parallel strategic/architecture/design review
- `prjct capture "<anything>"` — inbox dump (zero ceremony)
- `prjct remember <type> "<content>" [--tags]` — typed memory entry
- `prjct search "<query>"` — recall project memory (BM25 + semantic + recall); the verb to reach for when you need prior knowledge
- `prjct context memory [topic]` — same blended retrieval as `search`, plus `learnings`/`wiki` subtools
- `prjct guard <file>` — preventive memory recorded against a file, before you edit it
- `prjct workflow list` / `prjct workflow run <name>` — registered workflows
- `prjct seed list` — active packs (memory types + workflow slots)

Base memory types: `fact · decision · learning · gotcha · pattern · anti-pattern · shipped · inbox · todo · idea · insight · question · source · person · spec`. Any lowercase string works (e.g. `recipe`, `okr`, `stakeholder`).

### Data paths

- `.prjct/wiki/_generated/` — agent-crawlable markdown (regenerated on ship/remember)
- `.prjct/wiki/captured/` — drop notes with frontmatter, run `prjct context wiki sync` to ingest
- `.prjct/prjct.config.json` — persona + active packs

## Act: default DIRECT — escalation is the rare exception

**The first move on almost every turn is to just do the work DIRECTLY.** A fix, a one-file change, a capture, a question, anything the user frames as quick/direct work (in any language): `prjct task` → implement it yourself → `ship`. **NO spec, NO audit-spec, NO subagents, NO fan-out.** This is the common case and the safe default — when unsure, this is what you pick. Ask at most ONE line; never escalate just to be safe.

Escalate to the spec pipeline ONLY when the test is unambiguous: multi-file + new behavior AND ambiguous scope AND real/irreversible stakes (or the user explicitly frames goals/acceptance/risks). Then, and only then: `spec ─→ audit-spec ─→ task --spec <id> ─→ implement ─→ ship ─→ remember learning`. Forcing simple work through this pipeline is the #1 perf-killer — it burns tokens for zero protection.

**If you ever dispatch a subagent (Agent tool), set `model:` explicitly — never let it inherit yours.** Only the agent that WRITES code gets `model: "opus"`. Reviewing/judging (`review`, `security`, `investigate`, audit-spec reviewers) → `model: "sonnet"`. Pure routing/orchestration → `model: "haiku"`. A non-implementer left on the parent's max model is exactly why a task crawls and burns tokens. Not optional.

Heavy quality workflows (`review`, `qa`, `security`, `investigate`, `audit`, `audit-spec`), the parallel-implementer fan-out rules, decision-briefs, the `prjct prefs` protocol, the spec stations and builder ethos all live in `workflows.md` — **read it on demand when (and only when) you actually run one.** Do not preload it; do not reach for the menu on simple work.

**CONTENT LANGUAGE — author every stored memory in ENGLISH**, no matter what language the user speaks (Spanish, Japanese, German — any). When you `capture`/`remember`, translate the intent into a clean English entry; the persisted knowledge is always English. LLMs comprehend English better and embeddings stay high-quality in one canonical language — mixed-language content produces cross-language retrieval noise and extra token cost on every later recall.

## Verb intent map — you run the verb, the user never types it

On every turn ask: "what is the user trying to accomplish?" and match to a verb below. The user may phrase intent in ANY language — the verbs are language-agnostic. These are *signals*, not phrase templates. The **Tier** column governs whether you auto-run or confirm first (see Routing).

| Intent / signal | Verb | Tier |
|---|---|---|
| starting a unit of work — "do X for me", a fix, a change, picking up a queue item (THE DEFAULT, most turns) | `prjct task "<desc>"` (add `--spec <id>` if a spec exists) | 2 |
| framing genuinely complex work WITH goals/stakes/acceptance criteria (the exception) | `prjct spec "<title>"` | 2 |
| harden / pressure-test an existing spec before any code | `prjct audit-spec <id>` | 2 |
| need prior project knowledge — "what did we decide about X", "find what we had on Y", recall before re-reading source | `prjct search "<query>"` | 1 |
| an interesting thought to keep, no commitment yet | `prjct capture "<text>" --tags topic:<x>` | 1 |
| a non-trivial choice just got resolved (+ its why) | `prjct remember decision "<choice + one-line why>"` | 1 |
| an insight / "aha" / new mental model | `prjct remember learning "<insight>"` | 1 |
| a non-obvious trap surfaced (+ how to avoid) | `prjct remember gotcha "<trap + how to avoid>"` | 1 |
| categorize the active task (type/domain/priority) | `prjct tag type:bug domain:auth …` | 1 |
| about to edit a file — check for known traps | `prjct guard <file>` | 1 |
| work is done, push it | `prjct ship` | 2 |
| lifecycle change on the active task | `prjct status done\|paused\|active` | 2 |
| "is the codebase healthy?" | `prjct health --md` | 1 |
| "what did we accomplish?" | `prjct retro 7d --md` | 1 |
| pause / resume the working context | `prjct context-save` / `prjct context-restore --md` | 1 |

Disambiguators: the "why" separates a `decision` from an `inbox` dump — if you can't state it in one line, capture as inbox. A bare "fix X" is `task`, never `spec`. `audit-spec` requires an existing spec. For `ship`, if the active task has a `linked_spec_id`, ship surfaces the spec's acceptance_criteria as a PR checklist — STOP on any unmet criterion (override: `prjct ship --no-spec-gate`).

## Routing — Tier governs auto-run vs confirm (by blast radius)

- **Tier 1 — auto-execute, one-line confirm.** `search`, `capture`, `tag`, `remember`, `guard`, `context-save`, `health`, `retro`, `prefs check/list`. Additive/read-only: run IMMEDIATELY, emit one line (`✓ saved as decision: …`). Do not ask "want me to save that?" — just save it; the user corrects afterward. Pausing for permission on routine captures is what makes prjct useless.
- **Tier 2 — suggest-and-confirm, ONE line.** `task`, `spec`, `audit-spec`, `ship`, `status done|paused`, `prefs set`. State intent + blast radius in one line and wait for a green light (an affirmative in any language, or silence). Never run `ship` without surfacing the plan first — it is un-doable without a force-push.
- **Tier 3 — decision-brief** (hard forks costing >5 min to undo): `prjct prefs check <id>` first, then the decision-brief format. Both detailed in `workflows.md`.

## Gotchas

- Memory recall is best-effort — an empty result means no match, not "nothing exists".
- Tags are freeform strings — reuse existing vocabulary before inventing new keys.
- Secret-like content is refused by `remember` and `capture` unless `--force`.
- Bare `prjct "<text>"` routes to `capture` (inbox), not `task`. Use `prjct task` explicitly for work that needs a branch/worktree.
- Hooks in `~/.claude/settings.json` already inject persona + topical memory on SessionStart / UserPromptSubmit — you rarely need to call prjct by hand at session start.
- **Worktree hygiene.** If you are working inside a git worktree, clean it up so they don't pile up on the local machine: AFTER the branch's PR is *merged* (not at session end — an open PR keeps its worktree), `git worktree remove <path>` + `git worktree prune`, run from the MAIN worktree (git won't remove the worktree you're standing in). NEVER remove a worktree with uncommitted or unpushed work, and never `--force` over a dirty tree (it silently discards work).