From 4e7c3d0afbdd97e8ca6955d9ea7404a5f82d1d62 Mon Sep 17 00:00:00 2001
From: nrslib <38722970+nrslib@users.noreply.github.com>
Date: Fri, 30 Jan 2026 21:01:00 +0900
Subject: [PATCH] update README

---
 CLAUDE.md | 204 ++++++++++++++++++++++++++++++++------------
 README.md | 248 +++++++++++++++++++++++++++++++-----------------------
 2 files changed, 295 insertions(+), 157 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 5699f00..4993e9d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-TAKT (Task Agent Koordination Tool) is a multi-agent orchestration system for Claude Code. It enables YAML-based workflow definitions that coordinate multiple AI agents through state machine transitions.
+TAKT (Task Agent Koordination Tool) is a multi-agent orchestration system for Claude Code. It enables YAML-based workflow definitions that coordinate multiple AI agents through state machine transitions with rule-based routing.
 
 ## Development Commands
 
@@ -25,35 +25,75 @@ TAKT (Task Agent Koordination Tool) is a multi-agent orchestration system for Cl
 | `takt /watch` | | Watch `.takt/tasks/` and auto-execute tasks (resident process) |
 | `takt /add-task` | `/add` | Add a new task interactively (YAML format, multiline supported) |
 | `takt /list-tasks` | `/list` | List task branches (try merge, merge & cleanup, or delete) |
-| `takt /switch` | | Switch workflow interactively |
+| `takt /switch` | `/sw` | Switch workflow interactively |
 | `takt /clear` | | Clear agent conversation sessions (reset state) |
+| `takt /eject` | | Copy builtin workflow/agents to `~/.takt/` for customization |
 | `takt /refresh-builtin` | | Update builtin resources from `resources/` to `~/.takt/` |
 | `takt /help` | | Show help message |
 | `takt /config` | | Display current configuration |
 
+GitHub issue references: `takt #6` fetches issue #6 and executes it as a task.
+
 ## Architecture
 
 ### Core Flow
 
 ```
 CLI (cli.ts)
-  → Slash commands (/run-tasks, /watch, /add-task, /list-tasks, /switch, /clear, /refresh-builtin, /help, /config)
-  → or executeTask()
+  → Slash commands or executeTask()
     → WorkflowEngine (workflow/engine.ts)
-      → runAgent() (agents/runner.ts)
-        → callClaude() (claude/client.ts)
-          → executeClaudeCli() (claude/process.ts)
-            → ClaudeProcess (claude-agent-sdk)
+      → Per step: 3-phase execution
+        Phase 1: runAgent() → main work
+        Phase 2: runReportPhase() → report output (if step.report defined)
+        Phase 3: runStatusJudgmentPhase() → status tag output (if tag-based rules)
+      → detectMatchedRule() → rule evaluation → determineNextStep()
+      → Parallel steps: Promise.all() for sub-steps, aggregate evaluation
 ```
 
+### Three-Phase Step Execution
+
+Each step executes in up to 3 phases (session is resumed across phases):
+
+| Phase | Purpose | Tools | When |
+|-------|---------|-------|------|
+| Phase 1 | Main work (coding, review, etc.) | Step's allowed_tools (Write excluded if report defined) | Always |
+| Phase 2 | Report output | Write only | When `step.report` is defined |
+| Phase 3 | Status judgment | None (judgment only) | When step has tag-based rules |
+
+Phase 2/3 are implemented in `src/workflow/phase-runner.ts`. The session is resumed so the agent retains context from Phase 1.
+
+### Rule Evaluation (5-Stage Fallback)
+
+After step execution, rules are evaluated to determine the next step. Evaluation order (first match wins):
+
+1. **Aggregate** (`all()`/`any()`) - For parallel parent steps
+2. **Phase 3 tag** - `[STEP:N]` tag from status judgment output
+3. **Phase 1 tag** - `[STEP:N]` tag from main execution output (fallback)
+4. **AI judge (ai() only)** - AI evaluates `ai("condition text")` rules
+5. **AI judge fallback** - AI evaluates ALL conditions as final resort
+
+Implemented in `src/workflow/rule-evaluator.ts`. The matched method is tracked as `RuleMatchMethod` type.
+
 ### Key Components
 
 **WorkflowEngine** (`src/workflow/engine.ts`)
 - State machine that orchestrates agent execution via EventEmitter
-- Manages step transitions based on agent response status
+- Manages step transitions based on rule evaluation results
 - Emits events: `step:start`, `step:complete`, `step:blocked`, `step:loop_detected`, `workflow:complete`, `workflow:abort`, `iteration:limit`
 - Supports loop detection (`LoopDetector`) and iteration limits
 - Maintains agent sessions per step for conversation continuity
+- Parallel step execution via `runParallelStep()` with `Promise.all()`
+
+**Instruction Builder** (`src/workflow/instruction-builder.ts`)
+- Auto-injects standard sections into every instruction (no need for `{task}` or `{previous_response}` placeholders in templates):
+  1. Execution context (working dir, edit permission rules)
+  2. Workflow context (iteration counts, report dir)
+  3. User request (`{task}` — auto-injected unless placeholder present)
+  4. Previous response (auto-injected if `pass_previous_response: true`)
+  5. User inputs (auto-injected unless `{user_inputs}` placeholder present)
+  6. `instruction_template` content
+  7. Status output rules (auto-injected for tag-based rules)
+- Localized for `en` and `ja`
 
 **Agent Runner** (`src/agents/runner.ts`)
 - Resolves agent specs (name or path) to agent configurations
@@ -63,17 +103,16 @@ CLI (cli.ts)
   - `supervisor`: Read/Glob/Grep/Bash/WebSearch/WebFetch
   - `planner`: Read/Glob/Grep/Bash/WebSearch/WebFetch
 - Custom agents via `.takt/agents.yaml` or prompt files (.md)
-- Supports Claude Code agents (`claudeAgent`) and skills (`claudeSkill`)
 
 **Claude Integration** (`src/claude/`)
-- `client.ts` - High-level API: `callClaude()`, `callClaudeCustom()`, `callClaudeAgent()`, `callClaudeSkill()`, status detection via regex patterns
-- `process.ts` - SDK wrapper with `ClaudeProcess` class, re-exports query management
+- `client.ts` - High-level API: `callClaude()`, `callClaudeCustom()`, `callClaudeAgent()`, `callClaudeSkill()`
+- `process.ts` - SDK wrapper with `ClaudeProcess` class
 - `executor.ts` - Query execution using `@anthropic-ai/claude-agent-sdk`
 - `query-manager.ts` - Concurrent query tracking with query IDs
 
 **Configuration** (`src/config/`)
 - `loader.ts` - Custom agent loading from `.takt/agents.yaml`
-- `workflowLoader.ts` - YAML workflow parsing with Zod validation (loads from `~/.takt/workflows/` only)
+- `workflowLoader.ts` - YAML workflow parsing with Zod validation; resolves user workflows (`~/.takt/workflows/`) with builtin fallback (`resources/global/{lang}/workflows/`)
 - `agentLoader.ts` - Agent prompt file loading
 - `paths.ts` - Directory structure (`.takt/`, `~/.takt/`), session management
 
@@ -82,74 +121,123 @@ CLI (cli.ts)
 - `watcher.ts` - TaskWatcher class for polling and auto-executing tasks (used by `/watch`)
 - `index.ts` - Task operations (getNextTask, completeTask, addTask)
 
+**GitHub Integration** (`src/github/issue.ts`)
+- Fetches issues via `gh` CLI, formats as task text with title/body/labels/comments
+
 ### Data Flow
 
-1. User provides task or slash command → CLI
-2. CLI loads workflow from `~/.takt/workflows/{name}.yaml`
-3. WorkflowEngine starts at `initialStep`
-4. Each step: `buildInstruction()` → `runStep()` → `runAgent()` → `callClaude()` → detect status → `determineNextStep()`
-5. Status patterns (regex in `statusPatterns`) determine next step via `transitions`
+1. User provides task (text or `#N` issue reference) or slash command → CLI
+2. CLI loads workflow: user `~/.takt/workflows/` → builtin `resources/global/{lang}/workflows/` fallback
+3. WorkflowEngine starts at `initial_step`
+4. Each step: `buildInstruction()` → Phase 1 (main) → Phase 2 (report) → Phase 3 (status) → `detectMatchedRule()` → `determineNextStep()`
+5. Rule evaluation determines next step name
 6. Special transitions: `COMPLETE` ends workflow successfully, `ABORT` ends with failure
 
-### Status Detection
-
-Agents output status markers (e.g., `[CODER:DONE]`) that are matched against `GENERIC_STATUS_PATTERNS` in `src/models/schemas.ts`. Common statuses: `done`, `blocked`, `approved`, `rejected`, `improve`, `in_progress`, `interrupted`.
-
 ## Directory Structure
 
 ```
 ~/.takt/                  # Global user config (created on first run)
   config.yaml             # Trusted dirs, default workflow, log level, language
-  workflows/              # Workflow YAML files (required location)
-  agents/                 # Agent prompt files (.md)
+  workflows/              # User workflow YAML files (override builtins)
+  agents/                 # User agent prompt files (.md)
 
 .takt/                    # Project-level config
   agents.yaml             # Custom agent definitions
   tasks/                  # Task files for /run-tasks
   reports/                # Execution reports (auto-generated)
-  logs/                   # Session logs (gitignored)
+  logs/                   # Session logs in NDJSON format (gitignored)
 
-resources/                # Bundled defaults (copied to ~/.takt on init)
+resources/                # Bundled defaults (builtin, read from dist/ at runtime)
   global/
     en/                   # English agents and workflows
     ja/                   # Japanese agents and workflows
 ```
 
+Builtin resources are embedded in the npm package (`dist/resources/`). User files in `~/.takt/` take priority. Use `/eject` to copy builtins to `~/.takt/` for customization.
+
 ## Workflow YAML Schema
 
 ```yaml
 name: workflow-name
 description: Optional description
-max_iterations: 10        # snake_case in YAML
+max_iterations: 10
+initial_step: plan        # First step to execute
 
 steps:
+  # Normal step
   - name: step-name
-    agent: ~/.takt/agents/default/coder.md  # Path to agent prompt
-    agent_name: coder                       # Display name (optional)
-    provider: codex                         # claude|codex (optional)
-    model: opus                             # Model name (optional)
+    agent: ../agents/default/coder.md   # Path to agent prompt
+    agent_name: coder                   # Display name (optional)
+    provider: codex                     # claude|codex (optional)
+    model: opus                         # Model name (optional)
+    edit: true                          # Whether step can edit files
+    permission_mode: acceptEdits        # Tool permission mode (optional)
     instruction_template: |
-      {task}
-      {previous_response}
-    pass_previous_response: true            # Default: true
-    transitions:
-      - condition: done
-        next_step: next-step
+      Custom instructions for this step.
+      {task}, {previous_response} are auto-injected if not present as placeholders.
+    pass_previous_response: true        # Default: true
+    report:
+      name: 01-plan.md                 # Report file name
+      format: |                         # Report format template
+        # Plan Report
+        ...
+    rules:
+      - condition: "Human-readable condition"
+        next: next-step-name
+      - condition: ai("AI evaluates this condition text")
+        next: other-step
       - condition: blocked
-        next_step: ABORT
-    on_no_status: complete    # complete|continue|stay
+        next: ABORT
+
+  # Parallel step (sub-steps execute concurrently)
+  - name: reviewers
+    parallel:
+      - name: arch-review
+        agent: ../agents/default/architecture-reviewer.md
+        rules:
+          - condition: approved       # next is optional for sub-steps
+          - condition: needs_fix
+        instruction_template: |
+          Review architecture...
+      - name: security-review
+        agent: ../agents/default/security-reviewer.md
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction_template: |
+          Review security...
+    rules:                            # Parent rules use aggregate conditions
+      - condition: all("approved")
+        next: supervise
+      - condition: any("needs_fix")
+        next: fix
 ```
 
+Key points about parallel steps:
+- Sub-step `rules` define possible outcomes but `next` is ignored (parent handles routing)
+- Parent `rules` use `all("X")`/`any("X")` to aggregate sub-step results
+- `all("X")`: true if ALL sub-steps matched condition X
+- `any("X")`: true if ANY sub-step matched condition X
+
+### Rule Condition Types
+
+| Type | Syntax | Evaluation |
+|------|--------|------------|
+| Tag-based | `"condition text"` | Agent outputs `[STEP:N]` tag, matched by index |
+| AI judge | `ai("condition text")` | AI evaluates condition against agent output |
+| Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-step matched conditions |
+
 ### Template Variables
 
 | Variable | Description |
 |----------|-------------|
-| `{task}` | Original user request |
-| `{iteration}` | Current iteration number |
-| `{max_iterations}` | Maximum iterations |
-| `{previous_response}` | Previous step output (requires `pass_previous_response: true`) |
-| `{user_inputs}` | Accumulated user inputs during workflow |
-| `{report_dir}` | Report directory name (e.g., `20250126-143052-task-summary`) |
+| `{task}` | Original user request (auto-injected if not in template) |
+| `{iteration}` | Workflow-wide iteration count |
+| `{max_iterations}` | Maximum iterations allowed |
+| `{step_iteration}` | Per-step iteration count |
+| `{previous_response}` | Previous step output (auto-injected if not in template) |
+| `{user_inputs}` | Accumulated user inputs (auto-injected if not in template) |
+| `{report_dir}` | Report directory name |
 
 ### Model Resolution
 
@@ -166,24 +254,34 @@ provider: claude
 model: opus          # Default model for all steps (unless overridden)
 ```
 
+## NDJSON Session Logging
+
+Session logs use NDJSON (`.jsonl`) format for real-time append-only writes. Record types:
+
+| Record | Description |
+|--------|-------------|
+| `workflow_start` | Workflow initialization with task, workflow name |
+| `step_start` | Step execution start |
+| `step_complete` | Step result with status, content, matched rule info |
+| `workflow_complete` | Successful completion |
+| `workflow_abort` | Abort with reason |
+
+Files: `.takt/logs/{sessionId}.jsonl`, with `latest.json` pointer. Legacy `.json` format is still readable via `loadSessionLog()`.
+
 ## TypeScript Notes
 
 - ESM modules with `.js` extensions in imports
 - Strict TypeScript with `noUncheckedIndexedAccess`
-- Zod schemas (v4 syntax) for runtime validation (`src/models/schemas.ts`)
+- Zod schemas for runtime validation (`src/models/schemas.ts`)
 - Uses `@anthropic-ai/claude-agent-sdk` for Claude integration
 
 ## Design Principles
 
 **Keep commands minimal.** One command per concept. Use arguments/modes instead of multiple similar commands. Before adding a new command, consider if existing commands can be extended.
 
-**Do NOT expand schemas carelessly.** The `TransitionConditionSchema` defines allowed condition values for workflow transitions. Do NOT add new values without strong justification. Use existing values creatively:
-- `done` - Task completed (minor fixes, successful completion)
-- `blocked` - Cannot proceed (needs plan rework)
-- `approved` - Review passed
-- `rejected` - Review failed, needs major rework
-- `improve` - Needs improvement (security concerns, quality issues)
-- `always` - Unconditional transition
+**Do NOT expand schemas carelessly.** Rule conditions are free-form text (not enum-restricted). However, the engine's behavior depends on specific patterns (`ai()`, `all()`, `any()`). Do not add new special syntax without updating the loader's regex parsing in `workflowLoader.ts`.
+
+**Instruction auto-injection over explicit placeholders.** The instruction builder auto-injects `{task}`, `{previous_response}`, `{user_inputs}`, and status rules. Templates should contain only step-specific instructions, not boilerplate.
 
 ## Isolated Execution (Shared Clone)
 
diff --git a/README.md b/README.md
index daa2c9d..4394d0e 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,9 @@ npm install -g takt
 # Run a task (will prompt for workflow selection and optional isolated clone)
 takt "Add a login feature"
 
+# Run a GitHub issue as a task
+takt "#6"
+
 # Add a task to the queue
 takt /add-task "Fix the login bug"
 
@@ -75,7 +78,7 @@ Choose `y` to run in a `git clone --shared` isolated environment, keeping your w
 
 | Workflow | Best for |
 |----------|----------|
-| `default` | Full development tasks. Used for TAKT's own development. Multi-stage review with fix loops. |
+| `default` | Full development tasks. Used for TAKT's own development. Multi-stage review with parallel architect + security review. |
 | `simple` | Lightweight tasks like README updates or small fixes. Reviews without fix loops. |
 | `expert-review` / `expert-cqrs` | Web development projects. Multi-expert review (CQRS, Frontend, Security, QA). |
 | `research` | Research and investigation. Autonomous research without asking questions. |
@@ -86,67 +89,111 @@ Choose `y` to run in a `git clone --shared` isolated environment, keeping your w
 | Command | Alias | Description |
 |---------|-------|-------------|
 | `takt "task"` | | Execute task with current workflow (session auto-continued) |
+| `takt "#N"` | | Execute GitHub issue #N as a task |
 | `takt /run-tasks` | `/run` | Run all pending tasks from `.takt/tasks/` |
 | `takt /watch` | | Watch `.takt/tasks/` and auto-execute tasks (stays resident) |
 | `takt /add-task` | `/add` | Add a new task interactively (YAML format, multiline supported) |
 | `takt /list-tasks` | `/list` | List task branches (try merge, merge & cleanup, or delete) |
 | `takt /switch` | `/sw` | Switch workflow interactively |
 | `takt /clear` | | Clear agent conversation sessions |
+| `takt /eject` | | Copy builtin workflow/agents to `~/.takt/` for customization |
 | `takt /refresh-builtin` | | Update builtin agents/workflows to latest version |
 | `takt /config` | | Configure permission mode |
 | `takt /help` | | Show help |
 
 ## Workflows
 
-TAKT uses YAML-based workflow definitions. Place them in:
-- `~/.takt/workflows/*.yaml`
+TAKT uses YAML-based workflow definitions with rule-based routing. Builtin workflows are embedded in the package; user workflows in `~/.takt/workflows/` take priority. Use `/eject` to copy a builtin to `~/.takt/` for customization.
 
 ### Example Workflow
 
 ```yaml
 name: default
 max_iterations: 10
+initial_step: plan
 
 steps:
   - name: plan
-    agent: planner
-    provider: claude         # Optional: claude or codex
-    model: opus              # Claude: opus/sonnet/haiku, Codex: gpt-5.2-codex/gpt-5.1-codex
+    agent: ../agents/default/planner.md
+    model: opus
+    edit: false
+    rules:
+      - condition: Plan complete
+        next: implement
     instruction_template: |
-      {task}
-    transitions:
-      - condition: done
-        next_step: implement
+      Analyze the request and create an implementation plan.
 
   - name: implement
-    agent: coder
-    provider: codex
-    model: gpt-5.2-codex     # Codex model example
+    agent: ../agents/default/coder.md
+    edit: true
+    permission_mode: acceptEdits
+    rules:
+      - condition: Implementation complete
+        next: review
+      - condition: Cannot proceed
+        next: ABORT
     instruction_template: |
-      {task}
-    transitions:
-      - condition: done
-        next_step: review
-      - condition: blocked
-        next_step: ABORT
+      Implement based on the plan.
 
   - name: review
-    agent: architect
-    model: sonnet            # Model alias (no provider = uses global default)
-    transitions:
-      - condition: approved
-        next_step: COMPLETE
-      - condition: rejected
-        next_step: implement
+    agent: ../agents/default/architecture-reviewer.md
+    edit: false
+    rules:
+      - condition: Approved
+        next: COMPLETE
+      - condition: Needs fix
+        next: implement
+    instruction_template: |
+      Review the implementation for architecture and code quality.
 ```
 
+### Parallel Steps
+
+Steps can execute sub-steps concurrently with aggregate evaluation:
+
+```yaml
+  - name: reviewers
+    parallel:
+      - name: arch-review
+        agent: ../agents/default/architecture-reviewer.md
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction_template: |
+          Review architecture and code quality.
+      - name: security-review
+        agent: ../agents/default/security-reviewer.md
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction_template: |
+          Review for security vulnerabilities.
+    rules:
+      - condition: all("approved")
+        next: supervise
+      - condition: any("needs_fix")
+        next: fix
+```
+
+- `all("X")`: true if ALL sub-steps matched condition X
+- `any("X")`: true if ANY sub-step matched condition X
+- Sub-step `rules` define possible outcomes; `next` is optional (parent handles routing)
+
+### Rule Condition Types
+
+| Type | Syntax | Description |
+|------|--------|-------------|
+| Tag-based | `"condition text"` | Agent outputs `[STEP:N]` tag, matched by index |
+| AI judge | `ai("condition text")` | AI evaluates the condition against agent output |
+| Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-step results |
+
 ## Built-in Workflows
 
 TAKT ships with several built-in workflows:
 
 | Workflow | Description |
 |----------|-------------|
-| `default` | Full development workflow: plan → implement → architect review → AI review → security review → supervisor approval. Includes fix loops for each review stage. |
+| `default` | Full development workflow: plan → implement → AI review → parallel reviewers (architect + security) → supervisor approval. Includes fix loops for each review stage. |
 | `simple` | Simplified version of default: plan → implement → architect review → AI review → supervisor. No intermediate fix steps. |
 | `research` | Research workflow: planner → digger → supervisor. Autonomously researches topics without asking questions. |
 | `expert-review` | Comprehensive review with domain experts: CQRS+ES, Frontend, AI, Security, QA reviews with fix loops. |
@@ -158,9 +205,9 @@ Switch between workflows with `takt /switch`.
 ## Built-in Agents
 
 - **coder** - Implements features and fixes bugs
-- **architect** - Reviews code and provides feedback
-- **supervisor** - Final verification and approval
-- **planner** - Task analysis and implementation planning
+- **architect** - Reviews architecture and code quality, verifies spec compliance
+- **supervisor** - Final verification, validation, and approval
+- **planner** - Task analysis, spec investigation, and implementation planning
 - **ai-reviewer** - AI-generated code quality review
 - **security** - Security vulnerability assessment
 
@@ -175,14 +222,19 @@ agents:
     allowed_tools: [Read, Glob, Grep]
     provider: claude             # Optional: claude or codex
     model: opus                  # Claude: opus/sonnet/haiku or full name (claude-opus-4-5-20251101)
-    status_patterns:
-      approved: "\\[APPROVE\\]"
-      rejected: "\\[REJECT\\]"
+```
 
-  - name: my-codex-agent
-    prompt_file: .takt/prompts/analyzer.md
-    provider: codex
-    model: gpt-5.2-codex         # Codex: gpt-5.2-codex, gpt-5.1-codex, etc.
+Or create agent prompt files as Markdown:
+
+```markdown
+# ~/.takt/agents/my-agents/reviewer.md
+
+You are a code reviewer focused on security.
+
+## Your Role
+- Check for security vulnerabilities
+- Verify input validation
+- Review authentication logic
 ```
 
 ## Model Selection
@@ -217,22 +269,22 @@ Available Codex models:
 ```
 ~/.takt/
 ├── config.yaml          # Global config (provider, model, workflows, etc.)
-├── workflows/           # Workflow definitions
-└── agents/              # Agent prompt files
+├── workflows/           # User workflow definitions (override builtins)
+└── agents/              # User agent prompt files
 
 .takt/                   # Project-level config
 ├── agents.yaml          # Custom agent definitions
 ├── tasks/               # Pending task files (.yaml, .md)
 ├── completed/           # Completed tasks with reports
-├── worktree-meta/       # Metadata for task branches
-├── worktree-sessions/   # Per-clone agent session storage
 ├── reports/             # Execution reports (auto-generated)
-└── logs/                # Session logs (incremental)
+└── logs/                # Session logs in NDJSON format
     ├── latest.json      # Pointer to current/latest session
     ├── previous.json    # Pointer to previous session
-    └── {sessionId}.json # Full session log per workflow run
+    └── {sessionId}.jsonl # NDJSON session log per workflow run
 ```
 
+Builtin resources are embedded in the npm package (`dist/resources/`). User files in `~/.takt/` take priority.
+
 ### Global Configuration
 
 Configure default provider and model in `~/.takt/config.yaml`:
@@ -268,67 +320,59 @@ This interactive flow ensures each task runs with the right workflow and isolati
 
 ### Adding Custom Workflows
 
-Create your own workflow by adding YAML files to `~/.takt/workflows/`:
+Create your own workflow by adding YAML files to `~/.takt/workflows/`, or use `/eject` to customize a builtin:
+
+```bash
+# Copy the default workflow to ~/.takt/workflows/ for editing
+takt /eject default
+```
 
 ```yaml
 # ~/.takt/workflows/my-workflow.yaml
 name: my-workflow
 description: My custom workflow
-
 max_iterations: 5
+initial_step: analyze
 
 steps:
   - name: analyze
     agent: ~/.takt/agents/my-agents/analyzer.md
+    edit: false
+    rules:
+      - condition: Analysis complete
+        next: implement
     instruction_template: |
-      Analyze this request: {task}
-    transitions:
-      - condition: done
-        next_step: implement
+      Analyze this request thoroughly.
 
   - name: implement
     agent: ~/.takt/agents/default/coder.md
-    instruction_template: |
-      Implement based on the analysis: {previous_response}
+    edit: true
+    permission_mode: acceptEdits
     pass_previous_response: true
-    transitions:
-      - condition: done
-        next_step: COMPLETE
+    rules:
+      - condition: Done
+        next: COMPLETE
+    instruction_template: |
+      Implement based on the analysis.
 ```
 
+> **Note**: `{task}`, `{previous_response}`, and `{user_inputs}` are auto-injected into instructions. You only need explicit placeholders if you want to control their position in the template.
+
 ### Specifying Agents by Path
 
 Agents are specified using file paths in workflow definitions:
 
 ```yaml
-# Use built-in agents
+# Relative to workflow file directory
+agent: ../agents/default/coder.md
+
+# Home directory
 agent: ~/.takt/agents/default/coder.md
-agent: ~/.takt/agents/magi/melchior.md
 
-# Use project-local agents
-agent: ./.takt/agents/my-reviewer.md
-
-# Use absolute paths
+# Absolute paths
 agent: /path/to/custom/agent.md
 ```
 
-Create custom agent prompts as Markdown files:
-
-```markdown
-# ~/.takt/agents/my-agents/reviewer.md
-
-You are a code reviewer focused on security.
-
-## Your Role
-- Check for security vulnerabilities
-- Verify input validation
-- Review authentication logic
-
-## Output Format
-- [REVIEWER:APPROVE] if code is secure
-- [REVIEWER:REJECT] if issues found (list them)
-```
-
 ### Task Management
 
 TAKT supports batch task processing through task files in `.takt/tasks/`. Both `.yaml`/`.yml` and `.md` file formats are supported.
@@ -339,6 +383,9 @@ TAKT supports batch task processing through task files in `.takt/tasks/`. Both `
 # Quick add (no isolation)
 takt /add-task "Add authentication feature"
 
+# Add a GitHub issue as a task
+takt /add-task "#6"
+
 # Interactive mode (prompts for isolation, branch, workflow options)
 takt /add-task
 ```
@@ -416,11 +463,13 @@ Lists all `takt/`-prefixed branches with file change counts. For each branch you
 
 ### Session Logs
 
-TAKT writes session logs incrementally to `.takt/logs/`. Logs are saved at workflow start, after each step, and at workflow end — so even if the process crashes mid-execution, partial logs are preserved.
+TAKT writes session logs in NDJSON (`.jsonl`) format to `.takt/logs/`. Each record is appended atomically, so even if the process crashes mid-execution, partial logs are preserved and logs can be tailed in real-time with `tail -f`.
 
 - `.takt/logs/latest.json` - Pointer to the current (or most recent) session
 - `.takt/logs/previous.json` - Pointer to the previous session
-- `.takt/logs/{sessionId}.json` - Full session log with step history
+- `.takt/logs/{sessionId}.jsonl` - NDJSON session log with step history
+
+Record types: `workflow_start`, `step_start`, `step_complete`, `workflow_complete`, `workflow_abort`.
 
 Agents can read `previous.json` to pick up context from a prior run. Session continuity is automatic — simply run `takt "task"` to continue where the previous session left off.
 
@@ -430,57 +479,48 @@ Available variables in `instruction_template`:
 
 | Variable | Description |
 |----------|-------------|
-| `{task}` | Original user request |
+| `{task}` | Original user request (auto-injected if not in template) |
 | `{iteration}` | Workflow-wide turn count (total steps executed) |
 | `{max_iterations}` | Maximum iterations allowed |
 | `{step_iteration}` | Per-step iteration count (how many times THIS step has run) |
-| `{previous_response}` | Previous step's output (requires `pass_previous_response: true`) |
-| `{user_inputs}` | Additional user inputs during workflow |
+| `{previous_response}` | Previous step's output (auto-injected if not in template) |
+| `{user_inputs}` | Additional user inputs during workflow (auto-injected if not in template) |
 | `{report_dir}` | Report directory name (e.g., `20250126-143052-task-summary`) |
 
 ### Designing Workflows
 
-Each workflow step requires three key elements:
+Each workflow step requires:
 
 **1. Agent** - A Markdown file containing the system prompt:
 
 ```yaml
-agent: ~/.takt/agents/default/coder.md    # Path to agent prompt file
-agent_name: coder                          # Display name (optional)
+agent: ../agents/default/coder.md    # Path to agent prompt file
+agent_name: coder                    # Display name (optional)
 ```
 
-**2. Status Rules** - Define how the agent signals completion. Agents output status markers like `[CODER:DONE]` or `[ARCHITECT:REJECT]` that TAKT detects to drive transitions:
+**2. Rules** - Define how the step routes to the next step. The instruction builder auto-injects status output rules so agents know what tags to output:
 
 ```yaml
-status_rules_prompt: |
-  Your final output MUST include a status tag:
-  - `[CODER:DONE]` if implementation is complete
-  - `[CODER:BLOCKED]` if you cannot proceed
+rules:
+  - condition: "Implementation complete"
+    next: review
+  - condition: "Cannot proceed"
+    next: ABORT
 ```
 
-**3. Transitions** - Route to the next step based on status:
+Special `next` values: `COMPLETE` (success), `ABORT` (failure).
 
-```yaml
-transitions:
-  - condition: done        # Maps to status tag DONE
-    next_step: review      # Go to review step
-  - condition: blocked     # Maps to status tag BLOCKED
-    next_step: ABORT       # End workflow with failure
-```
-
-Available transition conditions: `done`, `blocked`, `approved`, `rejected`, `improve`, `answer`, `always`.
-Special next_step values: `COMPLETE` (success), `ABORT` (failure).
-
-**Step options:**
+**3. Step options:**
 
 | Option | Default | Description |
 |--------|---------|-------------|
+| `edit` | - | Whether the step can edit project files (`true`/`false`) |
 | `pass_previous_response` | `true` | Pass previous step's output to `{previous_response}` |
-| `on_no_status` | - | Behavior when no status is detected: `complete`, `continue`, `stay` |
 | `allowed_tools` | - | List of tools the agent can use (Read, Glob, Grep, Edit, Write, Bash, etc.) |
 | `provider` | - | Override provider for this step (`claude` or `codex`) |
 | `model` | - | Override model for this step |
 | `permission_mode` | `default` | Permission mode: `default`, `acceptEdits`, or `bypassPermissions` |
+| `report` | - | Report file configuration (name, format) for auto-generated reports |
 
 ## API Usage