woostack
Core concepts

Building rules

The plain-artifact local-authority build loop, optional Linear, Plane, or GitHub mirroring, and bounded one-PR routes.

The user owns product decisions. Git and GitHub prove repository delivery. Project-backed work retains its specification, plan, and recovery state locally; bounded work uses its active approved contract.

Workflow scope

ShapeCommandsActive contractProvider mirror behavior
Bounded bug or regressionwoostack-fixproved diagnosis and complete user-approved correction/verificationnone
Bounded non-bug changewoostack-changeone explicit goal/contractnone
Larger or explicitly project-backed fixwoostack-fixcomplete user-verified specification and increment planoptional mirror
Multi-increment featurewoostack-buildplain specification plus direct-issue graphlocal run manifest, direct increment contracts, dependencies (optional Linear, Plane, or GitHub mirror)
Greenfield codebasewoostack-bootstrapcomplete approved designexact artifact or explicit persistence request only

The shape of the work determines the workflow. Development records cannot turn ambiguous scope into a complete contract or replace direct repository evidence.

Planning and informed approval

The workflow map owns the human-readable Build/Fix sequence. Ideate collects complete user-verified decisions; Harden reconciles them against repository evidence one discrepancy at a time. Technical details do not become approved merely because they match existing code. Plan records outcomes, scope, acceptance, verification, material risks, and sequential dependency/parent bindings rather than prescribing each coding step or estimating changed lines.

Build and project-backed Fix use the verified handoff. The user sees the complete artifacts before choosing whether to execute, stop, or abandon. Clear natural-language choices are accepted; ambiguity or a material change to the approved contract cannot start execution.

The artifact contract owns persistence, base-change admission, mirrors, and recovery. A changed integration parent tip still requires the user's explicit choice before source mutation.

Execution invariants

  • One independently shippable increment maps to at most one PR.
  • Execute accepts --run <exact-run-id> [--recheck], --project <...>, or --issue <...>. Sequential execution within each run; distinct runs in isolated worktrees may run concurrently when responsibility surfaces do not collide.
  • Each active task has one controller identity, branch, collision-safe worktree, allowed surface, and current head.
  • Implementation may run inline or in an isolated worker. Focused verification, the real changed-path smoke scenario, and independent specification validation precede commit/PR delivery.
  • Graphite preserves stack ancestry. GitHub proves PR/head/base/check/review/merge state.
  • Every workflow stops on scope, ancestry, collision, evidence, or review drift. No workflow merges.

Canonical local records and optional remote mirroring

Build and project-backed Fix use local authority by default. Provider selection and native resource semantics live in the configuration reference and the linked provider profiles, not a second workflow definition here. Bounded Fix and Change make no provider calls.

Run artifacts are retained after completion or abandonment. Abandoning a local run leaves its mirror unchanged. Standalone provider lifecycle operations follow the selected profile and never confer source-control authority.

Authority boundaries

SurfaceAuthority
User request and decisionsinitiates the selected workflow and authorizes decisions
Local run manifest (.woostack/tmp/runs/<run-id>/)project-backed scope, plans, contracts, and recovery state
Git and GitHubsource, ancestry, commits, PRs, checks, reviews, merge evidence
Graphitestack and branch operations
Audit, QA, response reportssanitized non-authoritative diagnostic evidence
The Hermes guide documents how an external engineer can review harness evidence
without receiving implementation authority.

On this page