🧠 Persistent Context
Persistent Context is versioned knowledge that guides AI agents: rules, tasks, workflows, and past decisions.
Why
Agents need your conventions and decisions in a reusable form. Commit them once instead of repeating them in every chat.
Primitives
Four file types guide agents: instructions (rules), prompts (tasks), skills (workflows), and agents (specialists). See coding-pal for when and how to use each. coding-pal also publishes catalogs of instructions, prompts, skills, and agents.
Persistent Context across the stages
Persistent Context supports 0 — Meet through 5 — Prove. 7 — Learn enriches Persistent Context in return:
| Stage | What Persistent Context does there |
|---|---|
| 0 — Meet | Supplies the domain glossary, specifications, and meeting agent instructions and prompts, and receives new client terminology back |
| 1 — Triage | Grounds the qualification and mapping of requirements to existing capabilities and domain glossaries |
| 2 — Think | Supplies architectural invariants, decision records, and domain boundaries that bound the options |
| 3 — Plan | Informs constraints and non-functional invariants carried into the plan |
| 4 — Code | Guides AI agents with repository conventions, type rules, and execution skills |
| 5 — Prove | Constrains agent auto-remediation loops so automated patches comply with decision records and contracts |
| 7 — Learn | Receives new instructions, prompts, skills, agents, and decision records from production evidence |
Who owns it
The Architect owns Persistent Context, with every team contributing changes through pull requests.
Where it lives
Persistent Context lives in two places, depending on how widely it applies.
| Project-specific | Shared (global and generic) | |
|---|---|---|
| What | What only this application needs: its own instructions, specifications, and decision records | What every project needs: coding standards, test conventions, and generic agents, skills, and prompts |
| Where | In the application repository, next to the code it describes | In a dedicated repository, such as coding-pal |
| How it reaches a project | It is already there, and is reviewed like the code it describes | It is installed into each project with a package manager (coding-pal uses APM), so one change reaches every project |
Both are committed, reviewed through pull requests, and versioned.
Rules
- Committed, reviewed, versioned. A context artifact changes through a pull request.
- Evidence-driven. New artifacts come from 7 — Learn: something was corrected twice, or re-explained twice.
- Small and specific. Instructions that try to cover everything get ignored by models and humans alike.
- Scoped precisely. Instructions declare the narrowest matching pattern that works; broad patterns waste context on every request.
- Deleted when wrong. An outdated instruction is worse than none: it produces confident, consistent, wrong output.
- Never contains secrets. Context artifacts are read by tools and shared across sessions.
Health signals
| Signal | Healthy | Unhealthy |
|---|---|---|
| Fix-loop iterations needed | Trending down (1–2 loops) | Flat or above 3 loops |
| Manual human corrections during validation | Near zero | Frequent |
| Instruction count | Stable, each one used | Growing without pruning |
| First-pass green rate in Code | > 80% | < 50% |
| Generated output matching codebase conventions | High | Requires rewriting |