Core principles

Treat repository knowledge as part of the product

An agent can act reliably only on knowledge it can reach while working. Put durable engineering knowledge in versioned, reviewable repository artifacts; keep external systems for narrative or coordination that does not need to shape execution. Give every important document an owner, a discoverable path, and a way to notice drift.

Do not turn the root instruction file into an encyclopedia. Use it as a map containing:

• the repository’s purpose and shape;
• non-negotiable environment and safety constraints;
• commands needed for common validation;
• mandatory workflow triggers;
• links to deeper sources of truth.

This supports both humans and agents: newcomers get a route through the system, while routine work does not pay the context cost of every available rule.

Optimise for progressive disclosure

Place information at the narrowest useful scope:

• Repository-wide facts and routing belong in root instructions or a documentation index.
• Subsystem conventions belong in subsystem docs or path-scoped instructions.
• Repeatable judgement or procedures belong in a focused skill.
• Repeatable mechanics belong in a script, command, linter, test, or hook.
• Large examples and references belong in skill support files loaded only when needed.
• Generated facts belong in generated docs with a declared source and regeneration command.

The placement test is simple: if every task must know it, keep it small and always available; if only some tasks need it, make it discoverable on demand; if a machine can decide it consistently, encode it in a deterministic tool.

Design workflows as contracts

A reusable workflow should state:

• what inputs or repository state trigger it;
• when it must not run;
• the allowed tools and side effects;
• the expected artifact or decision;
• the success and failure conditions;
• whether human approval is required before mutation.

Narrow contracts make skills easier to route, scripts easier to test, and reviews easier to evaluate. Report-first workflows are a useful default for tasks such as documentation synchronisation, coverage improvement, migration planning, or release review: inspect and recommend first, then edit with explicit authority.

Make feedback improve the harness

Treat recurring review feedback and operational failures as evidence of a missing system capability. Feed the lesson into the lightest durable layer:

• clarify a map or focused guide when knowledge was missing;
• improve skill routing when the right procedure was not selected;
• add an executable check when a rule can be verified mechanically;
• expose better logs, UI state, or metrics when the agent could not observe the result;
• add an evaluation when behaviour is important but probabilistic.

This is continual maintenance, not a one-time prompt-writing exercise. Higher agent throughput increases the need for automated architecture checks, documentation hygiene, and deliberate cleanup.

Make outcomes observable and reviewable

An agent needs the same feedback loops a human engineer uses. Make the application runnable in an isolated change environment and expose focused UI state, logs, metrics, traces, test results, and generated artifacts. Prefer queryable signals and explicit thresholds over screenshots without context or unbounded log dumps.

Evidence should survive the turn that produced it. Record the baseline, failure reproduction, commands, results, before/after demonstration, skipped checks, and remaining risk in files or structured events. A final chat message is a termination signal, not the complete audit record.

Enforce invariants centrally and calibrate autonomy

Use mechanical checks for dependency direction, data-boundary validation, structured logging, generated-file policy, and other high-value invariants. Write failures so they explain remediation. Within those boundaries, allow implementation freedom where stylistic uniformity has little value.

Increase autonomy only after the repository can establish a clean baseline, reproduce failure, validate a fix, handle review and build failures, and escalate judgement calls. Merge gates follow impact and recovery economics; high agent throughput alone is not a reason to weaken them.