Skip to content

Commit edfaab6

Browse files
Chris0JekyChris0Jeky
authored
Merge pull request #1048 from Chris0Jeky/codex/agent-instructions-upgrade
Align agent routing guidance
2 parents 78b60dc + 18f3c55 commit edfaab6

30 files changed

Lines changed: 492 additions & 64 deletions

File tree

‎.claude/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Claude Code Workspace Guide
2+
3+
This `.claude/` layer contains Claude Code settings and skills for Taskdeck. It should stay aligned with `AGENTS.md`, `CLAUDE.md`, and the Codex-facing `.codex/` control plane.
4+
5+
## Start Here
6+
7+
1. Read [../docs/STATUS.md](../docs/STATUS.md).
8+
2. Read [CLAUDE.md](../CLAUDE.md).
9+
3. Read [AGENTS.md](../AGENTS.md).
10+
4. Read [../docs/IMPLEMENTATION_MASTERPLAN.md](../docs/IMPLEMENTATION_MASTERPLAN.md).
11+
5. Pick the matching skill from [skills/README.md](./skills/README.md).
12+
13+
## Coordination With Codex
14+
15+
- `.codex/README.md` and `.codex/memories/00_ACTIVE.md` are the Codex routing layer.
16+
- `.claude/settings.json` and `.claude/skills/*` are Claude Code's local execution layer.
17+
- Both systems use the same canonical Taskdeck docs under `docs/`.
18+
- If Claude and Codex guidance conflict, prefer `docs/STATUS.md` for current reality and `AGENTS.md` for repo-wide contributor protocol.
19+
20+
## Worktree Expectations
21+
22+
- Use `docs/WORKTREE_AGENT_PROTOCOL.md` for Claude `isolation: "worktree"` sessions.
23+
- Do not pass absolute main-checkout paths into worktree worker prompts.
24+
- First command in a worktree worker should validate isolation with the repo guard script.
25+
- Keep one coordinator responsible for final synthesis, docs updates, and verification claims.
26+

‎.claude/skills/README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Taskdeck Claude Skills
2+
3+
Claude Code skills live here and mirror the Taskdeck workflows exposed to Codex under `.codex/skills/`.
4+
5+
## High-Autonomy Skills
6+
7+
| Skill | Use it for |
8+
| --- | --- |
9+
| `taskdeck-issue-batch-orchestrator` | many issues, worker/worktree coordination, PR/review/CI batches, docs reconciliation |
10+
| `taskdeck-worktree-issue-worker` | one issue in an isolated worktree |
11+
| `taskdeck-pr-review-loop` | self-review, fresh adversarial review, review/bot comments |
12+
| `taskdeck-ci-conflict-recovery` | failing CI, stale branches, merge conflicts, blocked PRs |
13+
| `issue-to-pr` | simple one-issue-to-PR flow |
14+
15+
## Domain Skills
16+
17+
| Skill | Use it for |
18+
| --- | --- |
19+
| `taskdeck-repo-onramp` | broad orientation and current-reality reconciliation |
20+
| `taskdeck-backend-slice` | backend/API/application/infrastructure/worker/auth behavior |
21+
| `taskdeck-frontend-workspace-slice` | Vue workspace, routes, shell, stores, and UI polish |
22+
| `taskdeck-capture-review-loop` | capture, inbox, proposal review, execute, provenance, board handoff |
23+
| `taskdeck-demo-regression` | seeded demo evidence, Playwright proof, walkthrough validation |
24+
| `taskdeck-verification-doc-sync` | final checks, doc sync, handoff summary |
25+
26+
## Usage Pattern
27+
28+
1. Read `docs/STATUS.md`.
29+
2. Read `CLAUDE.md` and `AGENTS.md`.
30+
3. Choose the smallest matching skill set.
31+
4. Use `docs/tooling/CODEX_AUTONOMY_RUNBOOK.md` for shared high-autonomy batch discipline, substituting Claude entrypoints for Codex-specific preflight.
32+
5. Use `docs/WORKTREE_AGENT_PROTOCOL.md` for Claude worktree isolation.
33+
6. Report commands run, test results, docs updated, and unresolved risks.
34+

‎.claude/skills/taskdeck-backend-slice/SKILL.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@ Implement the smallest backend slice that fits the existing layering and contrac
99

1010
## Read first
1111

12-
1. `CLAUDE.md`
13-
2. `AGENTS.md`
14-
3. `docs/STATUS.md`
12+
1. `docs/STATUS.md`
13+
2. `CLAUDE.md`
14+
3. `AGENTS.md`
1515
4. `docs/GOLDEN_PRINCIPLES.md`
1616
5. `docs/TESTING_GUIDE.md`
1717

@@ -56,7 +56,7 @@ Do not move logic outward just to make a controller easier to write.
5656

5757
## Multi-agent split
5858

59-
If the task is broad, split by non-overlapping ownership:
59+
If the task is broad and the user authorized subagents, delegation, or parallel work, split by non-overlapping ownership:
6060

6161
- implementation in one layer or feature family
6262
- API contract or regression tests
@@ -65,4 +65,4 @@ If the task is broad, split by non-overlapping ownership:
6565
## Do not use this skill when
6666

6767
- the task is frontend-only, docs-only, or purely demo-evidence work
68-
- the task is really about capture/review semantics and needs the capture-review-loop skill as primary guide
68+
- the task is really about capture/review semantics and needs the capture-review-loop skill as primary guide

‎.claude/skills/taskdeck-ci-conflict-recovery/SKILL.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
name: taskdeck-ci-conflict-recovery
3+
description: Triage and fix Taskdeck PR failures involving CI, stale branches, merge conflicts, review comments, bot comments, or blocked checks.
4+
---
5+
6+
# Taskdeck CI And Conflict Recovery
7+
8+
Use this skill when a PR is blocked by CI, review/bot comments, conflicts, stale branches, or unclear checks.
9+
10+
## Read First
11+
12+
1. `docs/STATUS.md`
13+
2. `CLAUDE.md`
14+
3. `AGENTS.md`
15+
4. PR body, checks, comments, review threads, and linked issue
16+
5. `docs/TESTING_GUIDE.md`
17+
6. `docs/tooling/CODEX_AUTONOMY_RUNBOOK.md` for shared recovery discipline; substitute Claude entrypoints for Codex-specific preflight.
18+
19+
## Triage Sequence
20+
21+
1. Inspect failed checks and logs.
22+
2. Inspect review comments, bot comments, annotations, and artifacts.
23+
3. Classify each issue:
24+
- blocker
25+
- non-blocking risk
26+
- pre-existing noise
27+
- invalid signal
28+
4. Reproduce narrowly where practical.
29+
5. Fix root cause with focused commits.
30+
6. Re-run the smallest meaningful verification.
31+
7. Comment with what changed and what was verified.
32+
33+
## Conflict Rules
34+
35+
- Preserve both branches' intended behavior.
36+
- Prefer merge over rebase when conflict resolution starts stalling.
37+
- Do not rewrite history unless explicitly authorized.
38+
- Re-run tests for both sides of the conflict surface.
39+
40+
## Handoff
41+
42+
Report:
43+
44+
- checks/comments inspected
45+
- failures fixed
46+
- commands run and results
47+
- unresolved risk or missing access
48+
- any follow-up issues needed
49+

‎.claude/skills/taskdeck-demo-regression/SKILL.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,11 @@ Use Taskdeck's demo and regression tooling as evidence, not as a substitute for
99

1010
## Read first
1111

12-
1. `docs/TESTING_GUIDE.md`
13-
2. `docs/START_HERE.md`
14-
3. `docs/product/DEMO_PLAYBOOK.md`
15-
4. `docs/product/SCENARIOS.md`
12+
1. `docs/STATUS.md`
13+
2. `docs/TESTING_GUIDE.md`
14+
3. `docs/START_HERE.md`
15+
4. `docs/product/DEMO_PLAYBOOK.md`
16+
5. `docs/product/SCENARIOS.md`
1617

1718
## Evidence ladder
1819

@@ -41,4 +42,4 @@ Record:
4142
## Do not use this skill when
4243

4344
- a small code-path change is already fully proven by nearby automated tests
44-
- the task is final doc sync rather than evidence gathering
45+
- the task is final doc sync rather than evidence gathering

‎.claude/skills/taskdeck-frontend-workspace-slice/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ If the task changes capture, proposal review, provenance, or explicit board hand
4747

4848
## Multi-agent split
4949

50-
Good parallel splits:
50+
If the user authorized subagents, delegation, or parallel work, good parallel splits are:
5151

5252
- route or component implementation
5353
- store or API adjustments
@@ -56,4 +56,4 @@ Good parallel splits:
5656
## Do not use this skill when
5757

5858
- the task is backend-only
59-
- the main risk is in capture, proposal, execute, or provenance semantics rather than workspace UX
59+
- the main risk is in capture, proposal, execute, or provenance semantics rather than workspace UX

‎.claude/skills/taskdeck-issue-batch-orchestrator/SKILL.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
name: taskdeck-issue-batch-orchestrator
3+
description: Coordinate high-autonomy Taskdeck issue batches from selection through worktrees, PRs, review, CI recovery, docs reconciliation, and handoff. Use when asked to take care of many issues, pick next issues, coordinate agents, run review loops, or reconcile GitHub project status.
4+
---
5+
6+
# Taskdeck Issue Batch Orchestrator
7+
8+
Use this skill for Claude Code batch work. It mirrors the Codex workflow in `.codex/skills/taskdeck-issue-batch-orchestrator` while using Claude's worktree protocol where applicable.
9+
10+
## Read First
11+
12+
1. `docs/STATUS.md`
13+
2. `CLAUDE.md`
14+
3. `AGENTS.md`
15+
4. `docs/IMPLEMENTATION_MASTERPLAN.md`
16+
5. `docs/ISSUE_EXECUTION_GUIDE.md`
17+
6. `docs/GITHUB_PROJECT_AUTOMATION.md`
18+
7. `docs/tooling/CODEX_AUTONOMY_RUNBOOK.md` for shared batch discipline; substitute Claude entrypoints for Codex-specific preflight.
19+
8. `docs/WORKTREE_AGENT_PROTOCOL.md` when using Claude worktree agents
20+
21+
## Coordinator Responsibilities
22+
23+
The coordinator owns issue selection, dependency checks, worktree prompts, conflict resolution, PR quality, project status/priority sync, adversarial review assignment, CI/comment loops, docs rehydration, and final handoff.
24+
25+
Do not delegate final synthesis. Do not silently defer work.
26+
27+
## Work Splitting
28+
29+
Split only by non-overlapping ownership:
30+
31+
- one backend issue per worker
32+
- one frontend issue per worker
33+
- one docs-only issue per worker
34+
- one reviewer per PR
35+
- one CI/conflict worker per failing PR
36+
37+
Avoid concurrent edits to the same view, store, service, migration chain, project file, or canonical doc unless the coordinator controls merge order.
38+
39+
## Worker Setup
40+
41+
For isolated workers:
42+
43+
1. Use Claude `isolation: "worktree"` or the repo worktree script, depending on runtime.
44+
2. Do not include absolute main-checkout paths in worker prompts.
45+
3. Require the first command from `docs/WORKTREE_AGENT_PROTOCOL.md` or `powershell -File scripts/worktree_guard.ps1`.
46+
4. Assign explicit file/module ownership.
47+
5. Tell workers they are not alone in the codebase and must not revert others' edits.
48+
6. Require targeted tests and self-review before handoff.
49+
50+
## Review And CI
51+
52+
Every PR needs self-review. Sensitive PRs need fresh adversarial review:
53+
54+
- auth, sessions, tokens, security, secrets, redaction
55+
- migrations, persistence, deletion, import/export
56+
- capture, inbox, proposal review, execute, provenance
57+
- MCP or external-agent write surfaces
58+
- CI, project automation, scripts
59+
- broad frontend route/store/shell changes
60+
61+
Use `taskdeck-pr-review-loop` and `taskdeck-ci-conflict-recovery` for review and recovery work.
62+
63+
## Final Reconciliation
64+
65+
Before handoff, reconcile:
66+
67+
- `docs/STATUS.md` when shipped reality changed
68+
- `docs/IMPLEMENTATION_MASTERPLAN.md` when sequencing or delivery history changed
69+
- `docs/TESTING_GUIDE.md` when testing expectations or totals changed
70+
- `docs/MANUAL_TEST_CHECKLIST.md` or runbooks when manual verification became recurring
71+
- GitHub project `Status` and `Priority` when issue/PR state changed
72+

‎.claude/skills/taskdeck-pr-review-loop/SKILL.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
name: taskdeck-pr-review-loop
3+
description: Perform Taskdeck PR self-review or fresh adversarial review, inspect comments, post actionable findings, and verify fixes.
4+
---
5+
6+
# Taskdeck PR Review Loop
7+
8+
Use this skill for PR self-review, fresh adversarial review, and review-comment follow-up.
9+
10+
## Read First
11+
12+
1. `docs/STATUS.md`
13+
2. `CLAUDE.md`
14+
3. `AGENTS.md`
15+
4. PR title/body/diff/commits
16+
5. linked issue and acceptance criteria
17+
6. relevant docs: `docs/TESTING_GUIDE.md`, feature docs
18+
19+
## Review Stance
20+
21+
Prioritize actionable findings:
22+
23+
- behavioral regressions
24+
- security/authz gaps
25+
- migration/data-loss risk
26+
- missing tests or weak assertions
27+
- docs drift
28+
- CI, scripts, or project automation breakage
29+
- product-thesis violations around review-first automation
30+
31+
Use severities: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`. All accepted findings need a fix, invalidation evidence, or an explicit tracked follow-up.
32+
33+
## Review Output
34+
35+
For each finding include:
36+
37+
- severity
38+
- file and line
39+
- what can go wrong
40+
- expected fix
41+
- test or verification expectation
42+
43+
If no findings, say so and still name residual risk and test gaps.
44+
45+
## Fix Loop
46+
47+
When addressing findings:
48+
49+
1. map every finding to a fix, invalidation, or tracked follow-up
50+
2. make focused commits
51+
3. run targeted checks
52+
4. re-review the changed diff
53+
5. comment with fix evidence and verification results
54+

‎.claude/skills/taskdeck-repo-onramp/SKILL.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@ Establish current Taskdeck truth before editing code or docs.
99

1010
## Read first
1111

12-
1. `CLAUDE.md`
13-
2. `AGENTS.md`
14-
3. `docs/STATUS.md`
12+
1. `docs/STATUS.md`
13+
2. `CLAUDE.md`
14+
3. `AGENTS.md`
1515
4. `docs/IMPLEMENTATION_MASTERPLAN.md`
1616
5. `docs/GOLDEN_PRINCIPLES.md`
1717
6. `docs/ISSUE_EXECUTION_GUIDE.md`
@@ -52,7 +52,7 @@ Write a short plan covering:
5252

5353
## Multi-agent split
5454

55-
If work spans concerns, split by ownership:
55+
If the user authorized subagents, delegation, or parallel work, split by ownership:
5656

5757
- backend implementation agent
5858
- frontend implementation agent
@@ -63,4 +63,4 @@ Keep one coordinator responsible for synthesis and final verification.
6363
## Do not use this skill when
6464

6565
- the task is already tightly scoped in a familiar area
66-
- you only need final verification or doc sync
66+
- you only need final verification or doc sync

‎.claude/skills/taskdeck-verification-doc-sync/SKILL.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@ Finish the work completely: verify what changed, update the right docs, and repo
99

1010
## Read first
1111

12-
1. `AGENTS.md`
13-
2. `docs/TESTING_GUIDE.md`
14-
3. `docs/STATUS.md`
12+
1. `docs/STATUS.md`
13+
2. `AGENTS.md`
14+
3. `docs/TESTING_GUIDE.md`
1515
4. `docs/IMPLEMENTATION_MASTERPLAN.md`
1616

1717
Read when relevant:
@@ -51,4 +51,4 @@ Provide:
5151

5252
- a path is verified if you only reasoned about it
5353
- a feature is shipped if only demo tooling changed
54-
- canonical docs are current if implementation changed and the source-of-truth docs were left stale
54+
- canonical docs are current if implementation changed and the source-of-truth docs were left stale

0 commit comments

Comments
 (0)