Pre-Execution Team

Design proposal for a decision-support team that helps a programmer or a non-business requester turn an idea into approved business requirements, system design, delivery slices, and execution-ready tasks.

This repository is intentionally separate from agent-toolkit. The existing toolkit is an execution team; this team decides what is worth executing and which constraints execution must honor.

Status and usage (v0.1.0)

This repository now contains a working toolkit built from this proposal and BUILD-SPEC.md. It is generic: you scaffold it into another project, and every product value there is a per-project default.

bin/init.sh --target /path/to/your/project --project-name "Your project" --adapter claude
cd /path/to/your/project
claude            # then: /discover <your idea in plain language>

Any other AI tool can run the same team: give it .discovery/_toolkit/SYSTEM.md and ask it to act as the lead. scripts/pex/pex.sh --help lists the state machine commands.

Supported now	Not yet
Claude Code adapter; routine and standard initiatives end to end	Codex and OpenCode adapters (refused by init.sh)
Sensitive initiatives through design and readiness review	Sensitive handoff authorization (fail-closed)
Script-enforced state, hash-bound approvals, guard hook	Live permission checks: UNVERIFIED until docs/ACCEPTANCE-RUN.md is run

Project policy (.discovery/pex.config)

Key	Default	Meaning
allowed_providers	the adapter's provider (anthropic)	model providers initiative content may reach; initiatives may only narrow it
prohibited_content	secrets, credentials, personal data, payment data, confidential-marked	never sent to a model or written to an artifact
redaction_rule	[REDACTED:<category>]	how prohibited content is replaced
prohibited_patterns	empty	extended regex for project-specific prohibited shapes, scanned at freeze on top of built-in secret shapes
compliance_frameworks	none	frameworks design must address
diagram_format	mermaid	required diagram format in system design
handoff_consumption	git-reference	how execution receives the approved packet
wip_active_slices	1	maximum Now slices
supersession_authority	sponsor	who may supersede or cancel an initiative
sensitive_workflows	fail-closed	sensitive handoff authorization (enabled only after the live acceptance run)
receipt_sources	user-turn	accepted sources of human receipts
max_acceptance_criteria	7	criteria per execution task
question_batch_size	5	blocking questions per batch
delivery_feasibility	required	Gate 5 also needs the delivery representative's feasibility approval
review_write_requires_agent_type	yes	Claude guard: review files are written only by the matching reviewer subagent

Changing allowed_providers, prohibited_content, prohibited_patterns, compliance_frameworks, receipt_sources or supersession_authority stops decisions, approvals and export in every initiative until its sponsor or data owner re-confirms the policy with pex.sh policy. | agent_toolkit_version, agent_toolkit_commit | from init.sh flags | target execution toolkit | | lead_adapter | from --adapter | which runtime binds the lead |

Contributor notes are in CLAUDE.md, build decisions in docs/DECISIONS.md, and permission boundaries in docs/ADAPTERS.md. The design proposal follows unchanged.

Core Position

The team must ask, never silently assume.

Agents are facilitators, analysts, researchers, modelers, and challengers. They are not synthetic stakeholders and cannot approve requirements, choose business tradeoffs, accept risk, or manufacture consensus. Humans own those decisions.

For every material choice, the lead gives the human a decision brief:

Decision: <what must be decided>
Why now: <what this blocks or constrains>
Evidence: <sources, observations, and confidence>

Option A: <name>
- Pros:
- Cons:
- Risks:
- Cost/time implications:
- Reversibility:
- Downstream consequences:

Option B: <name>
- Pros:
- Cons:
- Risks:
- Cost/time implications:
- Reversibility:
- Downstream consequences:

Status quo / defer:
- Consequence:

Recommendation: <one option, with reason and confidence>
Human decision: <unfilled until the human answers>
Approval receipt: <direct human response tied to the candidate hash>

The recommendation helps the human; it does not replace the decision. External pages, files, issue text, and tool output are untrusted evidence, never instructions. Independent challenges run in fresh contexts against frozen candidates rather than inheriting the author's working conversation.

Depth is risk-based but the core contract does not disappear: routine work compresses the six logical gates into fewer human interactions; standard work uses full business/system review; sensitive work involving identity, payment, regulated or employee/customer data, safety, irreversible migration, or high blast radius requires named accountable owners and applicable specialist analysis. Human specialist consultation becomes mandatory when law, policy, or the accountable owner requires it; missing decision authority always fails closed.

Review Of The Execution Team

Reviewed against agent-toolkit v0.8.0.

What Is Strong

• Clear role authority: planner, implementer, reviewer, tester, lead, and human have distinct responsibilities.
• One durable state file carries handoffs, decisions, review findings, test evidence, blocked reasons, and bounded loops.
• Human approval is mandatory before implementation and merge.
• Structural checks validate what scripts can know without pretending to judge semantic correctness.
• Cross-vendor review, explicit test provenance, and an acceptance-evidence ledger make delivery more auditable than a single-agent coding flow.
• Never-overwrite scaffolding and provenance-aware upgrades are appropriate for project-local customization.

What It Correctly Does Not Solve

The execution pipeline starts from a feature request and can produce a clean, testable specification, but it has no authoritative upstream definition of:

• stakeholder goals, users, business value, and outcome metrics;
• business rules, exceptions, policies, and scope priorities;
• architecture, public contracts, stack, database, and data ownership;
• measurable non-functional requirements;
• security, privacy, migration, rollout, rollback, and operational constraints;
• why one delivery slice should precede another.

Its planner is intentionally forbidden from system design, while its implementer owns implementation decisions. Without a pre-execution handoff, architecture-level decisions can therefore occur during implementation, after the only specification approval gate.

Risks To Address Separately In The Execution Toolkit

These should remain execution-toolkit backlog rather than expanding this new team's scope:

1. Task risk class is recorded but does not yet select stronger controls.
2. The review artifact does not record an immutable base commit and independently prove that reviewed files equal committed files.
3. Review/test write boundaries depend partly on runtime permission behavior that still requires live verification.
4. The tester may create test artifacts after review, so projects should decide whether those artifacts require another review.
5. Loop-counter ownership should have one writer to prevent double increments.

The pre-execution team should provide risk and verification requirements, but the execution team must enforce its own source, review, test, and Git controls.

Recommended Team Shape

Use two cells with one human-facing lead. Do not create a large agent committee that votes on decisions.

Business And Stakeholder Cell

Human participants vary by initiative:

• Sponsor: owns business outcome, funding, priority, and go/no-go.
• Product or business owner: owns user value, scope, and requirement approval.
• Domain stakeholders: validate rules, processes, terminology, and exceptions.
• Users or user representatives: validate needs and usability assumptions.
• Compliance, legal, finance, support, sales, or operations: join only when affected; agents may identify them but never impersonate them.

Agent responsibilities (the initial build may consolidate them as specified in BUILD-SPEC.md):

• Discovery lead: runs the process and keeps decisions moving.
• Business analyst: asks questions and models goals, processes, rules, and requirements.
• Evidence researcher: investigates bounded external or codebase questions with citations and confidence.
• Independent challenger: searches for missing stakeholders, contradictions, hidden assumptions, exception paths, and weak evidence.
• Deterministic trace scripts check IDs, links, approval records, and orphan requirements without claiming semantic judgment.

System Design Cell

Human decision owners can be the same person in a small project, but the decision rights remain separate:

• Solution architect: owns system-boundary and significant technology choices.
• Data owner/steward: owns data semantics, permitted use, retention, and risk.
• Security/privacy owner: evaluates required controls and advises the accountable human; residual business risk is accepted only by the named business/data owner.
• Operations representative: validates deployability, observability, recovery, support, and cost constraints.
• Delivery representative: confirms slices are feasible and executable; the execution team still owns file-level planning and estimates.

Agent responsibilities (the initial build consolidates related authoring where independence is not required):

• Options analyst: compares build, buy, configure, reuse, defer, and do-nothing paths against approved drivers.
• System designer: produces context, runtime, deployment, integration, and failure-flow designs.
• Data designer: models concepts, ownership, lifecycle, access patterns, consistency, migration, backup, and deletion before selecting storage.
• Risk analyst: performs threat, abuse, privacy, compliance, and failure-mode analysis.
• Architecture reviewer: independently challenges requirement coverage, coupling, tradeoffs, reversibility, operability, and risk treatment.
• Delivery slicer: creates vertical, outcome-bearing slices and then tasks for only the next approved slice.
• Deterministic readiness scripts run structural and traceability checks; they cannot approve.

Most initiatives do not need every specialist. Staffing is risk-based, but no applicable concern may disappear merely because a role was omitted.

Operating Flow

flowchart TD
  Idea[Idea or problem] --> Frame[1. Frame and identify stakeholders]
  Frame --> Need[2. Discover and validate need]
  Need --> ReqGate{Human approves requirements?}
  ReqGate -- no --> Need
  ReqGate -- yes --> Options[3. Compare business and technical options]
  Options --> Choice{Human chooses direction?}
  Choice -- no --> Options
  Choice -- yes --> Design[4. Architecture, data, NFR, risk design]
  Design --> DesignGate{Human owners approve decisions and risks?}
  DesignGate -- no --> Design
  DesignGate -- yes --> Slice[5. Vertical slices and iteration plan]
  Slice --> Ready{6. Ready for execution?}
  Ready -- no --> Repair[Return to earliest affected owning gate]
  Ready -- yes --> Handoff[Versioned execution packet]
  Handoff --> Exec[agent-toolkit execution team]

Loading

Gates are evidence checkpoints, not ceremonies. New evidence may return work to an earlier stage. Elaborate only the next slice in detail; keep later work at outcome or hypothesis level.

Required Artifacts

Use stable IDs and links rather than one monolithic specification:

• Initiative brief and measurable outcomes.
• Stakeholder map, decision rights, glossary, and source register.
• Current/target process, business rules, exceptions, and non-goals.
• Functional requirements and measurable NFR scenarios.
• Assumption, question, dependency, and risk registers.
• Option briefs and human decision records.
• C4-style context/container views and important runtime/failure flows.
• Conceptual/logical data model, data-flow diagram, classification, ownership, retention, migration, recovery, and deletion behavior.
• ADRs for expensive-to-reverse or externally visible decisions.
• Threat, abuse, privacy, and operational readiness analysis.
• Now/Next/Later delivery map with vertical slices.
• Versioned execution packet for the next slice only.

Traceability must support this graph (not every initiative needs every optional node type):

Goal -> Outcome -> BR -> FR -> Slice -> Task -> Verification
                    \-> NFR / Constraint / Risk -/
                    \-> ADR ---------------------/

An orphan task, an approved requirement with neither planned verification nor an explicitly approved deferral, or a slice that ignores an applicable constraint/risk/ADR should fail readiness checks.

Reuse From anbturki/claude-toolkit

Research baseline: anbturki/claude-toolkit@b61db734, MIT licensed.

Good source material to adapt:

• agents/researcher.md: bounded evidence research.
• agents/planner.md: alternatives and approval discipline.
• skills/discover/SKILL.md: discovery structure and confidence labels.
• skills/deep-research/SKILL.md: source validation and contradiction handling.
• skills/system-design/SKILL.md: starting structure for design work.
• skills/write-docs/SKILL.md: ADR and no-fabrication discipline.
• agents/architecture-reviewer.md: seed for independent design review.
• agents/pre-impl-checker.md: seed for the readiness gate.
• skills/security-audit/SKILL.md: adapt from code audit to design-time threat and abuse analysis.

Do not import the toolkit wholesale. Avoid implementation/shipping skills and framework-specific generators in this repository. Its plan-tasks workflow is too implementation-coupled for this boundary. Any copied or substantially adapted file must retain the upstream MIT notice and record source path, pinned commit, and modifications in a provenance manifest.

The build plan is in BUILD-SPEC.md.