ryderfreeman4logos/mktd

mktd: Make TODO -- Debate-Enhanced Planning

Role Detection (READ THIS FIRST -- MANDATORY)

Role MUST be determined by explicit mode marker, not fragile natural-language substring matching. Treat the run as executor ONLY when initial prompt contains: <skill-mode>executor</skill-mode>.

YOU ARE THE EXECUTOR. Follow these rules:

1. SKIP the "Execution Protocol" section below -- it is for the orchestrator, not you.
2. Read the pattern at ../../PATTERN.md relative to this SKILL.md, and follow it step by step.
3. ABSOLUTE PROHIBITION: Do NOT run csa run, csa review, csa debate, or ANY csa command. You must perform the work DIRECTLY. Running any csa command causes infinite recursion.

Only if you are the main agent (Claude Code / human user):

• You are the orchestrator. Follow the "Execution Protocol" steps below.

---

Purpose

Generate a structured TODO plan for a feature through five phases: parallel CSA reconnaissance (structure, patterns, constraints, semantic invariants), draft synthesis, security threat model, mandatory adversarial debate review, and user approval gate. The main agent performs zero file reads during exploration -- CSA sub-agents gather all context. Plans are saved via csa todo for git-tracked lifecycle management. Epic-scale tasks are decomposed into summary TODO stories plus an epic-plan.toml dependency graph.

Intensity Modes

INTENSITY controls which phases run (default: full):

| Mode | Phases | Use Case | |------|--------|----------| | full | All phases including threat model + debate | Default: significant changes | | light | DRAFT → SPEC → SAVE → APPROVE (skips RECON, threat model, debate, revision) | Small changes (≤2 code files, <50 insertions) |

Pass via --var INTENSITY=light when invoking the workflow. dev2merge auto-selects based on change size.

Execution Protocol (ORCHESTRATOR ONLY)

Prerequisites

• Must be in a git repository with a feature branch checked out

Quick Start

csa run --sa-mode true --skill mktd "Plan the implementation of <feature description>"

# Light mode (small changes — skips threat model + debate):
csa plan run patterns/mktd/workflow.toml --var INTENSITY=light --var FEATURE="..." --var CWD="$(pwd)"

SA Mode Propagation (MANDATORY)

When operating under SA mode (e.g., dispatched by /sa or any autonomous workflow), ALL csa invocations MUST include --sa-mode true. This includes csa run, csa review, csa debate, and any other execution commands. Omitting --sa-mode at root depth causes a hard error; passing false when the caller is in SA mode breaks prompt-guard propagation.

Step-by-Step

1. Phase 1 -- RECON (skipped in light mode) (4 parallel CSA calls, tier-1):

   • RECON CSA calls are read-only by contract: workflow steps MUST set workspace_access = "read-only", which plan execution maps to a read-only project-root sandbox, and each RECON prompt MUST explicitly prohibit file edits or git-state writes.
   • Dimension 1 (Structure): Analyze codebase structure relevant to the feature (files, types, dependencies, entry points).
   • Dimension 2 (Patterns): Find existing similar features or reusable components.
   • Dimension 3 (Constraints): Identify breaking changes, security risks, performance concerns.
   • Dimension 4 (Semantic Invariants): Capture invariants, assumptions, concurrent writers, and failure/rollback model.
   • Main agent MUST NOT use Read/Glob/Grep/Bash for exploration.

   RECON Skip Condition: When ALL of the following are true, the orchestrator MAY skip CSA RECON and perform exploration directly (grep/read):

   • Change touches ≤3 files AND ≤50 lines
   • Relevant code is already in context OR locatable with ≤3 grep/read operations
   • No cross-crate dependency analysis needed This avoids the cold-start cost (~10K+ tokens per RECON session) for trivial changes. The orchestrator documents skipped RECON in the TODO draft with: RECON: skipped (small task, context sufficient).

2. Phase 1.5 -- LANGUAGE DETECTION: Resolve language by priority: ${USER_LANGUAGE} override -> ${CSA_USER_LANGUAGE} env -> script-aware detect from ${FEATURE} -> default Chinese (Simplified) when script is mixed/unknown -> fallback Chinese (Simplified) when ${FEATURE} is empty. This language is captured as ${STEP_2_OUTPUT}.

3. Phase 2 -- DRAFT: Synthesize CSA findings into a structured TODO plan with checkbox items, executor tags ([Main], [Sub:developer], [Skill:commit], [CSA:tool]), and descriptions in ${STEP_2_OUTPUT}. In light mode, RECON findings are intentionally empty and the draft uses the supplied feature brief plus already-available context. Every task MUST include a mechanically verifiable DONE WHEN: line. Technical terms, code snippets, commit scope strings, and executor tags remain in English.

4. Phase 2.5 -- THREAT MODEL (skipped in light mode): Review each new API surface for security concerns (sensitive data flows, hostile input, information exposure, safe defaults), plus concurrency-specific failure modes: concurrent writers, TOCTOU / rollback / cleanup races, state-machine invariants under concurrent transitions, and file-write atomicity. If the task is a default-change task (changes a default value, default transport, default tool, default feature gate, or default config field), emit an existing-config x upgrade-path matrix covering legitimate pre-change user states, pre-change behavior, post-change behavior, and whether a gap exists. Each matrix row with Gap = Yes MUST be tagged [Security] or [Compat] and added as a Phase-2.5-generated TODO item. Non-default-change tasks skip the matrix.

5. Phase 3 -- DEBATE (skipped in light mode): Run explicit csa debate (uses global [debate] config) via bash step, then normalize stdout into an evidence packet with headers: DEBATE_EVIDENCE, VALID_CONCERNS, SUGGESTED_CHANGES, OVERALL_ASSESSMENT. The red-team MUST enumerate every TODO-plan assumption and construct a counterexample scenario for each.

6. Phase 3.5 -- DEBATE VALIDATION (skipped in light mode): Hard-fail if required evidence headers, mapped verdict (READY|REVISE), raw verdict (APPROVE|REVISE|REJECT|UNKNOWN), or confidence are missing.

7. Phase 3b -- REVISE (skipped in light mode): Incorporate debate feedback and threat model findings. Concede valid points, defend sound decisions. Output the complete revised plan as text (stdout).

8. Phase 4 -- SAVE: Allocate the plan slot via csa todo create --branch <branch> --language <resolved-language> (returns the plan timestamp). The rendered TODO is ${STEP_12_OUTPUT} (revised plan) in full mode, falling back to ${STEP_7_OUTPUT} (draft plan) in light mode. Render the TODO, spec.toml (from ${STEP_8_OUTPUT}), and any epic-plan.toml to session-output artifacts under ${CSA_SESSION_DIR}/output/mktd-save/, then validate those rendered artifacts BEFORE committing (non-empty checkbox tasks, DONE WHEN clauses, spec criteria, language consistency) so an invalid plan never reaches the commit (round-5 ordering). Commit atomically with csa todo persist -t <timestamp> --todo-file <TODO.md> --spec-file <spec.toml> [--epic-plan-file <epic-plan.toml>] "finalize: <feature>", which writes and commits under one TODO write lock and re-validates the core invariants fail-closed. The persist step returns the saved TODO path as ${STEP_13_OUTPUT}.

9. Phase 4.25 -- PERSIST REFERENCES: Persist RECON findings, threat model, debate evidence, and a consolidated design.md reference using ${STEP_13_OUTPUT} as the saved TODO path anchor.

10. Phase 4.5 -- APPROVE: Present to user in ${STEP_2_OUTPUT} for APPROVE / MODIFY / REJECT.

Example Usage

| Command | Effect | |---------|--------| | /mktd global concurrency slots | Plan implementation of global concurrency slot feature | | /mktd "ACP transport layer" | Plan ACP transport implementation with debate review |

Reference Persistence

After the TODO plan is saved, RECON findings, threat model, and debate evidence SHOULD be persisted as references for progressive disclosure:

csa todo ref add -t <timestamp> --content "$RECON_OUTPUT" recon-structure.md

This allows agents executing the plan (via mktsk) to selectively load detailed context via csa todo ref show <name> without bloating their context window.

Integration

• Uses: debate (Phase 3 adversarial review)
• Feeds into: mktsk (converts approved TODO into executable Task entries)
• Lifecycle: Plans managed by csa todo (create, persist, show, find)
• References: RECON/debate findings persisted via csa todo ref add for progressive disclosure during plan execution

Done Criteria

1. Four RECON dimensions completed via CSA (structure, patterns, constraints, semantic invariants).
2. Main agent performed zero file reads during Phase 1.
3. TODO draft synthesized with executor tags and checkbox items.
4. Each task has >= 20 words of context/description.
5. Design Overview section is present with key decisions.
6. (full mode only) Threat model completed for all new API surfaces.
7. (full mode only) Adversarial debate completed via explicit csa debate.
8. (full mode only) Debate evidence packet validated (includes mapped verdict, raw verdict, and confidence).
9. (full mode only) Debate Findings section captures adopted vs deferred points.
10. (full mode only) TODO revised to incorporate debate feedback and threat model findings.
11. TODO saved via csa todo create + csa todo persist (artifact-file flow) with branch and language association.
12. Pre-persist validation gate checked the rendered artifacts for task completeness (- [ ] ..., DONE WHEN), spec criteria, and language consistency BEFORE the commit; csa todo persist re-validated the core invariants fail-closed under the write lock.
13. Design document and RECON references attempted via csa todo ref add (stored in ~/.local/state/cli-sub-agent/, not git-tracked).
14. User presented with plan for approval decision in resolved language.