Development
Pi Sych favors the smallest implementation that keeps state, delegation, review, and verification inspectable.
Before changing code
Read AGENTS.md, PROJECT.md,
docs/ARCHITECTURE.md, and relevant tests. A clear owner
instruction to implement a defined change, or an explicitly approved
PLAN.md, establishes the accepted task boundary. File
existence alone does not establish approval. Do not manufacture a new
checkpoint merely because authorized work is large; ask when a new
consequential choice falls outside the accepted boundary.
Keep semantic interpretation in skills and normal supervisor conversation; keep path, process, schema, hash, and persistence invariants mechanical in TypeScript.
For substantive behavior changes, use independent test design and read-only review when proportionate. Do not turn a narrow correction into a workflow controller, repository abstraction, or new policy layer.
Where changes belong
Use the code tour for the source map and the public contract to distinguish stable userland from internal implementation details.
| Change | Primary location | Related checks |
|---|---|---|
| Supervisor tool or lifecycle behavior | extensions/workbench/index.ts and
extensions/workbench/src/ |
Unit/integration tests and public contract |
| Worker launch, context, or terminal report | extensions/workbench/src/worker-engine.ts,
extensions/worker/index.ts |
Worker and process tests; architecture |
| Fingerprints or dependency acknowledgement | project-files.ts, project-status.ts |
State and acknowledgement tests; SYNC.json |
| Local literature discovery | literature-search.ts |
Database fixtures; configuration |
| Domain-specific review or writing behavior | Public skill, routed module, or shared method | Skill routing and task-level evaluation |
| Optional review interface | extensions/plannotator/ |
Adapter tests and review workflow |
| Optional review lens | prompts/review-*.md |
Prompt discovery and review skill consistency |
Do not turn a documentation-only clarification into a new runtime mechanism. Conversely, a behavior change must be documented where users encounter it, not only in the code tour.
Documentation and synchronization checks
For a documentation update, inspect the relevant implementation and
tests before asserting runtime behavior. Keep the README as orientation,
architecture as the mechanism-level explanation, public contract as the
compatibility authority, and code tour as a navigable source map. Use
docs/review-workflow.md for human/LLM feedback distinctions
and docs/review-prompts.md for optional review lenses.
Avoid repeating full skill instructions across these pages.
Review SYNC.json after changes to tracked documents. A
stored fingerprint that no longer matches is evidence of a change, not
permission to mark it approved. Update acknowledgement only after
reviewing the new content and declared dependent artifacts. Preserve
unresolved needs-review states and do not invent test
results or review timestamps.
make verify checks types, style, source budget,
coverage, packaging, and Git whitespace. Run make site
separately to check the published documentation build and links. The
opt-in usage suite includes worker-instructions.test.mjs,
which checks inline guidance through a live dispatch and verifies shared
worker files and project AGENTS remain unchanged, and
custom-compaction.test.mjs, which checks a live summary and
proposal. These require explicit opt-in and configured credentials;
model/run-specific results are not deterministic CI contracts. A remote
edit without a local checkout cannot establish that either repository
command passed; report that limitation.
Checks
Run the repository gate before treating substantive work as complete:
make verifyUse focused Make/npm targets while iterating.
npm run test:usage is an opt-in live-model evaluation and
is evidence rather than a deterministic contract.
Skill-architecture tests verify the seven public
SKILL.md files, hidden shared methods, required
guidance/examples, resolvable recipes, acyclic routes, and intended
specialist composition. They should not freeze semantic prose through
keyword assertions unless the wording itself is a public contract.
Model-facing text
Treat model-facing text as behavior-bearing interface surface. Put only high-salience cross-domain invariants in always-visible supervisor/tool text. Put domain posture and routing in umbrella skills. Put detailed procedure in routed methods/modules. Avoid duplicated instructions whose copies can drift or compete for attention.
Prefer concrete verbs, explicit authority and scope, short decision rules, and stated failure modes. Distinguish authorization from task size, persistence from scrutiny, and context need from delegation choice.
Design constraints
- No generic workflow DAG, fixed agent pipeline, or duplicate MCP/review implementation.
- No command/path pseudo-security or sandbox claims.
- No credentials, provider choices, model ranking, or personal examples in the public package.
- Workers receive one smallest-complete assignment; clean mode receives no supervisor transcript, while trajectory mode receives only the persisted branch before its exact dispatch entry.
- Clear user authorization covers the named scope; new consequential choices outside that scope remain human-owned.
- Never claim execution, retrieval, rendering, review, or verification that did not occur.