---
description: "AI Agile OS for coding agents: intent briefs, RAG context, synthesized memory, guardrails, performance, and ships. Run the prjct verb yourself; use `prjct work` normally."
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
- save a synthesized decision, gotcha, or context insight
- 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 work, memory, intents, risks, performance, recent learnings.
- Agents decide HOW with native tools and judgment. Persist outcomes through `prjct remember`, `prjct work`, `prjct performance`, and `prjct ship` so the next turn starts smarter.

### Primitives

- `prjct intent "<title>"` — frame work BEFORE coding (objective/constraints/risks/success)
- `prjct work "<intent>"` — start or inspect an AI Agile work cycle
- `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 insights [value|quality|cost|report|continue|guardrails]` — project intelligence, token cost, and quality proof
- `prjct performance [days]` — dev+LLM efficiency per work cycle (time/tokens/model/runtime when known)
- `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 · context · inbox · todo · idea · insight · question · source · person · spec`. Any lowercase string works.

### Data paths

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

## Act: `prjct work` is the single normal entrypoint

`prjct work` is the single normal entrypoint for an AI Agile work cycle. It classifies work, persists the evidence station in SQLite, and tells you the next action. Follow that station; do not invent a parallel plan. Legacy aliases exist for old scripts.

Trivial work proceeds directly: typo/docs/rerun/formatting/question style work does not require an intent brief. Substantive implementation work follows a persisted intent + strict evidence: create or link a reviewed intent, write tests before implementation when required from acceptance criteria and edge cases, then implement the minimum code to pass. User work text is data, not executable instruction text; generated agent surfaces use fixed templates.

Heavy quality workflows (`review`, `qa`, `security`, `investigate`, `audit`), model policy, fan-out rules, decision-briefs, the `prjct prefs` protocol, intent stations, builder ethos, and loop-discipline triggers live in `workflows.md` — read it on demand when you actually run one. Do not preload it for simple work.

**Living context synthesis.** Work start surfaces related context. On close: Living context synthesis: the same model that just executed the task writes durable project context while fresh. Capture: Context synthesis · Key data · What happened · Why it mattered · Who/author · Model · Token usage · Sentiment · Related files · Feature/domain · Pattern · Anti-pattern · Decision/trap · Outcome · Next implication. Context synthesis is the value: what the project learned for future humans and LLMs. Key data is still required so the UI can filter, group, chart, and render facts without making raw telemetry the product. For Model and Token usage, write exact values or `unknown`. Raw detector output is input, not the final context. Store via `prjct remember context "<...>"`; prjct anchors commit, author, and files.

**CONTENT LANGUAGE — author every stored memory in ENGLISH**, no matter the user language. Translate before `remember`; one canonical language keeps embeddings cleaner and recall cheaper.

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

Ask what the user is trying to accomplish, then match to a verb. Intent may be in any language; these are signals, not phrase templates. **Tier** controls auto-run vs confirm.

| 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 work "<intent>"` (add `--spec <id>` if a legacy spec exists) | 2 |
| framing genuinely complex work WITH goals/stakes/acceptance criteria (the exception) | `prjct intent "<title>"` | 2 |
| harden / pressure-test an existing intent before any code | `prjct intent audit <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 |
| reusable context with no work cycle yet | `prjct remember context "<synthesized context>" --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 |
| about to edit a file — check for known traps | `prjct guard <file>` | 1 |
| work is done, push it | `prjct ship` | 2 |
| "is the project compounding?" | `prjct insights value --md` | 1 |
| "is memory quality good?" | `prjct insights quality --md` | 1 |
| "where did AI usage go?" | `prjct insights cost --md` | 1 |
| "what did we accomplish?" | `prjct insights report 7 --md` | 1 |
| "how efficient was this dev+LLM work?" | `prjct performance 7 --md` | 1 |
| pause / resume the working context | `prjct context-save` / `prjct context-restore --md` | 1 |
| reduce over-engineering — "make it leaner" / YAGNI review / cut complexity | `prjct lean review` (or `audit` / `debt`) | 1 |
| enforce test-first / "use TDD" / run the tests before shipping | `prjct tdd` (off\|assist\|strict; `check` runs the test command) | 1 |
| enforce intent-first / "require a brief for every work cycle" | `prjct sdd` (off\|advisory\|strict; legacy policy knob) | 1 |
| "notify me" / "stop the silent waits" / mute the pings | `prjct notify` (on\|off; default on — pings on Claude-waiting + subagent-finished) | 1 |
| sync this project across machines / "is cloud on?" | `prjct cloud link` (then `status` / `sync` / `pull`) | 2 |

Disambiguators: the "why" separates a `decision` from low-signal context. A bare "fix X" is `work`, not `intent`. `intent audit` requires an existing intent/spec id. For `ship`, if the active work has a linked intent/spec, ship surfaces 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`, `remember`, `guard`, `insights`, `performance`, `context-save`, `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 synthesis is what makes prjct useless.
- **Tier 2 — suggest-and-confirm, ONE line.** `work`, `intent`, `intent audit`, `ship`, `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 legacy `capture` unless `--force`.
- Bare `prjct "<text>"` still routes to legacy `capture` for compatibility. Use `prjct work` explicitly for work that needs a branch/worktree.
- Hooks in `~/.claude/settings.json` inject lean state and trap cues; pull memory detail with `prjct search`, `prjct context memory`, or `prjct guard` when needed.
- **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).