Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions .takt/pieces/dual-core-apply.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
name: dual-core-apply
description: Phase 2 only. Run implement and fix after explicit human approval is confirmed.
interactive_mode: persona
initial_movement: implement
max_movements: 12

piece_config:
provider_options:
claude:
network_access: true
codex:
network_access: true

movements:
- name: implement
edit: true
permission_mode: edit
provider: claude
model: claude-opus-4-6[1m]
persona: coder
knowledge: architecture
allowed_tools: [Read, Glob, Grep, Edit, Bash]
instruction_template: |
Inputs: APPROVAL.md, PLAN.md, and AUDIT.md.
Precondition:
- APPROVAL.md must include all of the following fields with non-empty values:
Approved(Y/N), Reason, Timestamp.
- If APPROVAL.md is missing or Approved(Y/N) is not Y, do not implement anything.
Return status tag "blocked" with the reason.
Goal: implement according to PLAN.md and resolve audit findings.
Rules:
- Keep changes minimal and explain each change.
- Run relevant build/tests and document command outputs.
Deliverable:
- Implementation report including changed files, commands, and results.
output_contracts:
report:
- name: 04-implement-log.md
rules:
- condition: blocked
next: ABORT
- condition: done
next: fix

- name: fix
edit: true
permission_mode: edit
provider: codex
model: gpt-5.3-codex
persona: code-reviewer
knowledge: architecture
allowed_tools: [Read, Glob, Grep, Edit, Bash]
instruction_template: |
Goal: make minimal fixes for failed tests/build or quality issues.
Rules:
- Do not weaken test coverage to force a pass.
- Iterate as: identify root cause -> propose minimal fix -> apply -> verify.
Deliverable:
- Fix report with root cause, patch summary, rerun commands, and outcomes.
output_contracts:
report:
- name: 05-fix-log.md
rules:
- condition: done
next: COMPLETE
91 changes: 91 additions & 0 deletions .takt/pieces/dual-core-approval.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
name: dual-core-approval
description: Phase 1 only. Plan, audit, and build APPROVAL.md, then always stop for explicit human approval.
interactive_mode: persona
initial_movement: plan
max_movements: 12

piece_config:
provider_options:
claude:
network_access: true
codex:
network_access: true

movements:
- name: plan
edit: false
permission_mode: readonly
provider: claude
model: claude-opus-4-6[1m]
persona: architect-planner
knowledge: architecture
allowed_tools: [Read, Glob, Grep]
instruction_template: |
Goal: create PLAN.md at repository root before any code changes.
Constraints:
- Do not modify source code in this movement.
Deliverables:
- PLAN.md with requirements, candidate files, implementation steps, validation criteria,
rollback procedure, and risks.
- A short movement report summarizing key decisions.
output_contracts:
report:
- name: 01-plan-summary.md
rules:
- condition: done
next: audit

- name: audit
edit: false
permission_mode: readonly
provider: codex
model: gpt-5.3-codex
persona: security-reviewer
knowledge: architecture
allowed_tools: [Read, Glob, Grep]
instruction_template: |
Input: PLAN.md at repository root.
Goal: audit the plan for missing items, contradictions, security risks, dependency gaps,
and execution risks.
Deliverables:
- AUDIT.md at repository root with PASS/FAIL and evidence.
- Report with top 5 critical findings.
Constraint:
- Do not modify source code in this movement.
output_contracts:
report:
- name: 02-audit-top5.md
rules:
- condition: done
next: approval

- name: approval
edit: true
permission_mode: edit
provider: claude
model: claude-opus-4-6[1m]
persona: supervisor
knowledge: architecture
allowed_tools: [Read, Glob, Grep, Edit]
instruction_template: |
Inputs: PLAN.md and AUDIT.md.
Goal: generate APPROVAL.md at repository root as a pre-implementation approval packet.
Required sections in APPROVAL.md:
- Purpose
- Changed files list (planned)
- Change summary (3-7 bullets)
- Impact scope
- Commands to run and expected results
- Risk and unresolved items
- Rollback plan
- Approval fields: Approved(Y/N), Reason, Timestamp
Rules:
- Do not modify source code except APPROVAL.md in this movement.
- Choose Approved(Y/N) based on PLAN.md and AUDIT.md findings.
- Always produce APPROVAL.md and finish with status tag "done".
output_contracts:
report:
- name: 03-approval-gate.md
rules:
- condition: done
next: COMPLETE
2 changes: 1 addition & 1 deletion .takt/pieces/dual-core.yaml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
name: dual-core
description: Claude plans and implements, Codex audits and fixes with an explicit approval gate.
description: Legacy single-run flow. Claude plans/implements and Codex audits/fixes with model-driven approval routing.
interactive_mode: persona
initial_movement: plan
max_movements: 12
Expand Down
140 changes: 78 additions & 62 deletions Takt_setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,10 @@ Set up TAKT with:

- CLI OAuth only (no direct API key operation)
- Interactive mode as the default workflow
- Project-local `dual-core` piece:
- Plan (Claude) -> Audit (Codex) -> Approval (Claude) -> Implement (Claude) -> Fix (Codex)
- A hard approval gate that always stops before implementation
- Project-local dual-core pieces:
- Phase 1: Plan (Claude) -> Audit (Codex) -> Approval (Claude) -> STOP
- Phase 2: Implement (Claude) -> Fix (Codex)

This document also captures approvals required before production use.

Expand All @@ -19,10 +21,11 @@ This document also captures approvals required before production use.
- Primary execution mode: `interactive mode`
- Piece location: `project-local .takt/pieces`
- Approval scope before production: `all configuration changes`
- Interactive mode in piece: `persona`
- Interactive mode in pieces: `persona`
- Network access policy: `allowed in all movements`
- Approval packet policy: `APPROVAL.md required before implement`
- max movement policy: `max_movements = 12`, stop on limit with manual follow-up
- Hard gate policy: `approval phase always completes and requires explicit human Y/n before phase 2`

## 3. Preflight Checks (Executed)

Expand All @@ -49,55 +52,68 @@ Commands run and outcomes:

## 4. Changes Applied

1. Created piece file: `.takt/pieces/dual-core.yaml`
2. Enforced least-privilege movement design:
- `plan`, `audit`: readonly + read tools only
- `approval`, `implement`, `fix`: edit enabled for approval packet + implementation workflow
3. Routing configured:
- `plan -> audit -> approval -> implement -> fix -> COMPLETE`
4. Pinned movement models:
- Claude movements (`plan`, `approval`, `implement`): `claude-opus-4-6[1m]`
- Codex movements (`audit`, `fix`): `gpt-5.3-codex`
1. Added phase-1 piece: `.takt/pieces/dual-core-approval.yaml`
2. Added phase-2 piece: `.takt/pieces/dual-core-apply.yaml`
3. Added wrapper: `scripts/takt-run-approved.sh`
4. Kept legacy piece: `.takt/pieces/dual-core.yaml` (for backward compatibility)
5. Runtime safeguards:
- `interactive_mode: persona`
- `max_movements: 12`
- `network_access: true` remains enabled
- `network_access: true`
6. Pinned movement models:
- Claude movements: `claude-opus-4-6[1m]`
- Codex movements: `gpt-5.3-codex`

## 5. Approval Register (Production Gate)

All items below must stay approved before production tasks:

1. CLI OAuth only operation (no API key fallback): `APPROVED`
2. API key environment variables remain unset: `APPROVED`
3. `dual-core` piece permissions and movement order: `APPROVED`
3. piece permissions and movement order: `APPROVED`
4. Interactive-first operation (`/go` to execute piece): `APPROVED`
5. Approval packet requirement (`APPROVAL.md` before implement): `APPROVED`
6. Movement limit policy (`max_movements=12`, fail-stop): `APPROVED`
7. Hard stop at approval before implementation: `APPROVED`

## 6. Runbook

### Standard interactive run
### Recommended one-command run (hard approval gate)

```bash
takt -w dual-core --create-worktree yes --auto-pr
./scripts/takt-run-approved.sh -w dual-core --create-worktree yes --auto-pr

Copilot AI Feb 14, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The runbook recommends ./scripts/takt-run-approved.sh -w dual-core ..., but the wrapper ignores the provided -w/--piece value. To avoid confusion, update the documented command to omit -w dual-core (or document that it’s accepted but validated/ignored).

Suggested change
./scripts/takt-run-approved.sh -w dual-core --create-worktree yes --auto-pr
./scripts/takt-run-approved.sh --create-worktree yes --auto-pr

Copilot uses AI. Check for mistakes.
```

Then:
Behavior:

1. Choose or confirm interactive mode.
2. Refine task in chat.
3. Execute with `/go`.
4. Validate `APPROVAL.md` content before allowing implementation stage.
1. Runs phase 1 (`dual-core-approval`) and always stops after `approval` movement.
2. Locates and prints `APPROVAL.md`.
3. Verifies `APPROVAL.md` contains approved status and required fields.
4. Prompts: `Proceed with implementation? (Y/n)`.
5. Runs phase 2 (`dual-core-apply`) only when the user confirms.

### Direct execution (optional)
### Manual two-step run (optional)

```bash
takt --task "Create PLAN.md, audit it, build APPROVAL.md, then implement and fix until checks pass" --piece dual-core --create-worktree yes --auto-pr
takt -w dual-core-approval --create-worktree yes
```

Then verify approval packet and confirm in terminal:

```bash
cat APPROVAL.md
read -r -p "Proceed with implementation? (Y/n): " yn
```

If approved:

```bash
takt -w dual-core-apply --create-worktree no --auto-pr
```

## 7. Approval Gate (`APPROVAL.md`)

`approval` movement must create `APPROVAL.md` at repository root before implementation.
Phase 1 must create `APPROVAL.md` at repository root before implementation.

Required sections:

Expand All @@ -110,14 +126,13 @@ Required sections:
7. Rollback plan
8. Approval fields (`Approved: Y/N`, `Reason`, `Timestamp`)

Terminal approval operation:
Wrapper validation requires all of the following:

```bash
cat APPROVAL.md
read -r -p "Proceed with implementation? (Y/n): " yn
```
- `Approved: Y` (or `Approved (Y/N): Y`)
- Non-empty `Reason`
- Non-empty `Timestamp`

If approval is rejected, stop and re-run from planning/audit with updated task instructions.
If any check fails, phase 2 is blocked.

## 8. Model Override Policy

Expand All @@ -129,7 +144,7 @@ Model/provider choices are controlled with this policy:
4. Global/project config defaults
5. Provider defaults

Project default is movement pinning in `.takt/pieces/dual-core.yaml`.
Project default is movement pinning in `.takt/pieces/dual-core-approval.yaml` and `.takt/pieces/dual-core-apply.yaml`.

## 9. Fallback Procedure (`gpt-5.3-codex` unavailable)

Expand All @@ -138,51 +153,52 @@ If Codex movement fails because `gpt-5.3-codex` is unavailable in the current ro
1. Try one-off execution override:

```bash
takt --task "..." --piece dual-core --provider codex --model codex
takt --task "..." --piece dual-core-apply --provider codex --model codex
```

2. If still blocked, temporarily switch the Codex movement model in
`.takt/pieces/dual-core.yaml` from `gpt-5.3-codex` to `codex`, run the task,
then restore the original model string.
2. If still blocked, temporarily switch the Codex movement model in:

- `.takt/pieces/dual-core-approval.yaml`
- `.takt/pieces/dual-core-apply.yaml`

from `gpt-5.3-codex` to `codex`, run the task, then restore the original model string.

3. Record the fallback reason and command used in the run report.

## 10. Validation Scenarios

1. Piece load check
- Command: `takt prompt dual-core`
- Expectation: prompt preview starts and shows movements in order.
- Note: in `takt 0.13.0`, preview may still print `reportContent is required for report-based judgment` even with valid pieces.
2. Model pinning check
- Command: `rg -n "model:" .takt/pieces/dual-core.yaml`
- Expectation: five model entries exist (3 Claude, 2 Codex).
3. Interactive piece execution
- Command: `takt -w dual-core --create-worktree yes --auto-pr`
- Expectation: after `/go`, movements follow configured providers, permissions, and include `approval`.
4. Safety guard check
- Ensure API key variables are still empty before execution.
1. Piece load checks
- `takt prompt dual-core-approval`
- `takt prompt dual-core-apply`
2. Model pinning checks
- `rg -n "model:" .takt/pieces/dual-core-approval.yaml`
- `rg -n "model:" .takt/pieces/dual-core-apply.yaml`
3. Wrapper syntax check
- `bash -n scripts/takt-run-approved.sh`
4. Hard gate check
- Phase 1 ends before implementation starts.
- Wrapper asks `Proceed with implementation? (Y/n)`.
5. Approval packet check
- Command: `test -f APPROVAL.md && echo OK`
- Expectation: `APPROVAL.md` is created before implementation activity.
- `test -f APPROVAL.md && echo OK`
6. Movement limit check
- Confirm piece config has `max_movements: 12`.
- Expectation: run stops at movement limit and requires manual follow-up.
- Confirm both piece files have `max_movements: 12`.

## 11. Rollback / Recovery

If `dual-core` causes issues:
If this hard-gate flow causes issues:

1. Run with built-in piece temporarily:
- `takt` and choose default piece
2. Or bypass project piece by explicitly selecting another piece:
1. Use legacy piece temporarily:
- `takt -w dual-core`
2. Or run built-in default:
- `takt -w default`
3. Disable this piece by renaming file:
- `.takt/pieces/dual-core.yaml` -> `.takt/pieces/dual-core.yaml.disabled`
3. Disable new pieces and wrapper by removing:
- `.takt/pieces/dual-core-approval.yaml`
- `.takt/pieces/dual-core-apply.yaml`
- `scripts/takt-run-approved.sh`

## 12. Notes

- `takt` emitted an update-check permission warning for `~/.config`; this does not block normal execution.
- `takt prompt` currently emits a status-judgment error in this environment (`takt 0.13.0`), including for built-in pieces.
- `gpt-5.3-codex` and `[1m]` model behavior can depend on provider-side account and route availability.
- Terminal Y/n approval is an operational gate; enforce it consistently in runbook use.
- Keep this guide updated whenever piece permissions, auth policy, or execution mode changes.
- `takt` may emit an update-check permission warning for `~/.config`; this does not block normal execution.
- `takt prompt` may still print `reportContent is required for report-based judgment` in `takt 0.13.0`.
- `gpt-5.3-codex` and `[1m]` behavior depends on provider-side account and route availability.
- Legacy `.takt/pieces/dual-core.yaml` is kept for backward compatibility, but production runs should use the hard-gate wrapper.
Loading