willianbs Purpose
Build a minimal, sufficient CONTEXT_PACK so downstream skills decide with real project knowledge—not guesses.
When to Use / When NOT to Use
Use when: starting any non-trivial engineering task; user mentions “load context”, “what’s the architecture”, or engineering-os begins a path.
Do not use when: user already provided a Complete CONTEXT_PACK; or the task is a pure wording edit with zero code impact.
Preconditions
- A concrete task or question exists.
- Repo (or relevant paths) are accessible.
Inputs / Outputs
Inputs: task statement, optional hints (paths, ticket).
Outputs: CONTEXT_PACK
Upstream / Downstream
Upstream: engineering-os, model-router (optional).
Downstream: nearly all skills; especially spec-validator, adr-enforcer, delivery-planner, feature-implementer, defect-analyst.
Core Principles
- Sufficiency over completeness.
- Authoritative sources beat stale docs when they conflict—and conflicts must be reported.
- Token budget is a hard constraint.
- Prefer ADRs, interfaces, and entrypoints over trivia.
- Never invent missing context.
- Stop early when Blocked/Incomplete for risky work.
- Emit a portable artifact others can consume.
Process
Lite vs full
| Task risk | Mode |
|---|---|
| Typo, comment, tiny chore | lite: target files + nearest README only |
| Feature / bug / review | full discovery |
Full discovery
- Source priority (load in order, stop when sufficient):
- Task-named paths / ticket links
- Engineering guardrails (
docs/ENGINEERING_GUARDRAILS.md, thenAGENTS.md/.cursor/rules/summaries) - ADRs / architecture docs (
docs/adr/,adr/,ARCHITECTURE.md) - Package/workspace manifests
- Entry points and public APIs for touched areas
- Existing tests for those areas
- README / CONTRIBUTING for commands only
- Dependency discovery — only immediate neighbors of touched modules.
- Conflict detection — code vs docs vs ADR; list explicitly.
- Budget — default caps: ≤25 files or ~40k tokens of loaded content (whichever first). Summarize beyond that; cite paths instead of pasting.
- Completeness gate — Complete / MostlyComplete / Incomplete / Blocked.
Evidence Requirements
List every path actually read. Do not claim to have read files you skipped.
Stop Conditions / Failure Modes
| Condition | Action |
|---|---|
| Critical ADR/docs conflict for the task | Blocked |
| Cannot find any relevant code for named feature | Incomplete + questions |
| Budget exceeded before sufficiency | Summarize + MostlyComplete with gaps |
| No ADRs exist | Note NoADRs; do not invent architecture |
| No guardrails file on non-trivial work | Note NoGuardrails; suggest guardrails-configurator |
Severity + Confidence
N/A for most runs. Conflicts that could cause wrong implementation → treat as High risk in CONTEXT_PACK.
Output Contract
## CONTEXT_PACK
Completeness: Complete | MostlyComplete | Incomplete | Blocked
Summary: ...
Sources: [paths]
ADR IDs: ...
Conflicts: ...
Budget: files=N tokens≈M (caps ...)
Commands discovered: test/lint/build if found
Gaps / questions: ...
Decision: Proceed | ProceedWithConditions | Revise | Block
Handoffs
- adr-enforcer — on conflicts or NoADRs needing bootstrap
- spec-validator — if requirements unclear
- engineering-os — return pack and continue path
Never
- Never dump the whole repository.
- Never resolve architecture conflicts by picking a side silently.
- Never invent ADRs, APIs, or business rules.
- Never load secrets from
.envinto the pack; cite path only if needed and redact values.