Core concepts

woostack separates product decisions from repository delivery evidence. The user verifies what is being built; Git and GitHub prove source, ancestry, commits, pull requests, reviews, and merge state.

Two delivery shapes

• Bounded work: Change handles one non-bug enhancement or refactor. Fix proves a defect and obtains explicit approval of the complete correction and verification before one-PR delivery. Neither bounded route requires a project run or artifact-provider access.
• Project-backed work: Build and larger, uncertain, or explicitly project-backed fixes retain a complete specification, sequential increment plan, and recovery manifest under .woostack/tmp/runs/<run-id>/. Local authority is the default; Linear, Plane, and GitHub may mirror completed artifacts.

See Workflow maps for the sequences and Building rules for the approval and delivery boundaries.

Complete user understanding

Planning is a dialogue, not an agent-generated specification presented as settled fact. Ideate requires explicit user verification of material goals, behavior, exclusions, architecture, data models, API details, and verification expectations. Harden reconciles repository evidence one discrepancy at a time. Existing conventions and plausible defaults never replace the user's decision.

Plans describe outcomes and acceptance rather than predicting every implementation step or line count. That gives the implementer room to work without weakening the approved product contract.

Retained artifacts and optional mirrors

Project-backed workflows keep project-spec.md, execution-plan.md, and recovery state across completion, interruption, and abandonment. The artifact contract owns storage, exact resume, mirroring, and lifecycle details. A provider mirror cannot authorize repository work or override the local run.

Build and project-backed Fix present the verified artifacts before the user chooses whether to execute, stop, or abandon. Clear natural-language intent is accepted; changed scope returns to explicit verification. The Build handoff is canonical.

Context economy

Load the workflow and references needed for the current decision. Implement inline when delegation adds no useful separation; use isolated workers for substantial independent work or bounded context. Independent review and observed verification remain separate from implementation.

Session reflection becomes instruction suggestions

At an ordinary final-reply boundary, woostack-reflect is loaded only when the session already contains a concrete observed preventable instruction gap that could yield a durable instruction finding. Its candidate gate is canonical; a qualifying reply runs one report-only pass, while a reply with no candidate emits no reflection headings.

Diagnostic outputs from audit, QA, or production-response workflows are similarly non-authoritative. They may support a decision; remediation enters the appropriate fix, change, or build workflow under its own contract.

Tools compute, agents read compact results

Small helpers gather and validate deterministic evidence so agents can concentrate on engineering judgment. Review prefetch gathers the relevant diff, metadata, and repository rules once. Run-store operations enforce filesystem integrity; workflow decisions still require user verification.

External engineers and coding harnesses

Hermes is an external engineer, not an installed coding harness. It may drive a persistent OMP session, review evidence, and relay the responsible user's live decisions verbatim; it does not gain implementation authority. See the Hermes guide for that boundary and cross-session resume.

Where to go next