fix: move mode into spec level

Author: kanfil

.implementation-notes.md

@@ -0,0 +1,30 @@
+# Per-Spec Mode Implementation Notes
+
+## Status: Phase 2 In Progress
+
+### Completed (Phase 1):
+- ✅ Created detect-workflow-config.sh and .ps1
+- ✅ Exported to common.sh/ps1
+- ✅ All tests passing
+
+### Completed (Phase 2 Partial):
+- ✅ Updated /specify template with parameters
+- ✅ Updated spec-template.md and spec-template-build.md with metadata
+- ✅ Added parameter parsing to create-new-feature.sh
+
+### In Progress:
+- 🔄 Complete create-new-feature.sh (lines 331-380 need mode variable substitution)
+- 🔄 Update /architect to accept --mode parameters
+- 🔄 Update /plan, /tasks, /implement to auto-detect from spec.md
+
+### Remaining:
+- Update create-new-feature.ps1
+- Remove /mode command
+- Update config.json schema
+- Documentation updates
+- End-to-end testing
+
+## Key Design Decision:
+- `/specify` and `/architect` → Accept mode parameters (CREATE documents)
+- `/plan`, `/tasks`, `/implement` → Auto-detect from spec.md (READ mode)
+- No redundant mode parameters in downstream commands

roadmap.md

@@ -503,6 +503,106 @@ Consolidates: Command-level model selection + context budgeting + two-model revi
 
 ## 🚀 **NEXT PHASE** (Deferred - Complete After Current Phase)
 
+### **Worktrunk-Integrated Parallel Execution with Dependency-Aware Orchestration** *(0% Complete)* - **HIGH PRIORITY** - Incident.io workflow pattern enabling 5+ agents in parallel with git worktree isolation
+
+**Purpose**: Enable safe parallel execution of SYNC/ASYNC tasks with explicit dependency tracking and phase-respecting orchestration. Validates the incident.io pattern (multiple agents, branch isolation, clean merge workflow) using Worktrunk as optional infrastructure for parallel development.
+
+**Design Foundation** (locked design from validated patterns):
+
+| Aspect | Decision | Validation |
+|--------|----------|-----------|
+| Branch Structure | Hierarchical: `feature/spec-name/task-NNN-description-[sync\|async]` | Nests task branches under spec branch from `/specify`; prevents collision |
+| Dependencies | Explicit in tasks.md: `depends: [T001, T002]` | Human-writable during `/plan`; pre-merge hooks validate; enables sophisticated scheduling |
+| Phase Ordering | Enforce phase boundaries; parallelize `[P]` within phase | Setup → Foundational → Stories; respects internal dependencies |
+| Unmet Dependencies | Skip task with warning; don't block phase | Graceful degradation; visibility into blocking tasks |
+| Worktree Isolation | Optional (Worktrunk); sequential fallback | Enables incident.io pattern; functional without worktrees |
+| Worktree Paths | Full hierarchical: `repo.feature.spec-name.task-NNN-desc` | Fully qualified; prevents collision across features |
+
+**Implementation Roadmap** (5 Phases, 10 Weeks):
+
+##### Phase 1: Dependency Model & Parsing (Weeks 1-2)
+- [ ] Update `templates/tasks-template.md` with `depends: [T001, T002]` syntax + examples
+- [ ] Create `scripts/bash/parse-dependencies.sh` with DAG validation (cycles, cross-phase violations, missing refs)
+- [ ] Create PowerShell equivalent: `scripts/powershell/Parse-Dependencies.ps1`
+- [ ] Update `/tasks` template to emit dependency syntax
+- [ ] Update `docs/triage-framework.md` with dependency declaration guidance
+
+**Testing**: Sample tasks.md with 10+ tasks across 3 phases; verify DAG validation
+
+##### Phase 2: Phase-Aware Orchestration (Weeks 3-4)
+- [ ] Create `scripts/bash/orchestrate-tasks.sh` with phase-sequential + [P] parallelization logic
+- [ ] Create PowerShell equivalent: `scripts/powershell/Orchestrate-Tasks.ps1`
+- [ ] Extend `/implement` template to call orchestration logic
+- [ ] Add phase-aware progress reporting ("Phase 1/3: 2/3 tasks complete")
+
+**Testing**: Full workflow on test project with 10+ tasks; verify sequential Setup, parallel Foundational
+
+##### Phase 3: Worktrunk Integration (Optional) (Weeks 5-6)
+- [ ] Create `scripts/bash/spawn-task-worktree.sh` with worktree creation + branch hierarchy
+- [ ] Create PowerShell equivalent: `scripts/powershell/Spawn-TaskWorktree.ps1`
+- [ ] Generate `.config/wt.toml` template with pre-merge dependency validation hooks
+- [ ] Extend `/implement` to detect Worktrunk + choose execution path
+- [ ] Add `--enable-worktrunk`, `--prefer-worktrunk` (default), `--no-worktrunk` flags
+
+**Testing**: Run with Worktrunk available and without; verify isolation and fallback
+
+##### Phase 4: Remote Async Agent Integration (Weeks 7-8) *(Tier 1.3 + 1.4 enablement)*
+- [ ] Extend `dispatch_async_task()` to include worktree branch SHA + path (if available)
+- [ ] Create `scripts/bash/package-task-context.sh` bundling spec, plan, research, task spec
+- [ ] Update delegation template with task dependency metadata
+- [ ] Extend `tasks-meta-utils.sh` to track async task status from remote agents
+
+**Testing**: Delegate ASYNC task with full worktree context; verify agent receives branch info
+
+##### Phase 5: Monitoring & Documentation (Weeks 9-10)
+- [ ] Create monitoring dashboard script: `scripts/bash/monitor-parallel-tasks.sh`
+- [ ] Update `/implement` output to show phase progress, pending dependencies, agent status
+- [ ] Create comprehensive guide: `docs/parallel-execution-guide.md`
+- [ ] Create end-to-end integration test: `test-parallel-execution.sh`
+
+**Testing**: Complete workflow with 3 phases, mixed SYNC/ASYNC, dependencies; verify monitoring
+
+**Integration with Existing Framework**:
+
+- **Enhances [P] Markers** (line 56-61): Existing `[P]` parallelization now coordinated via Worktrunk worktrees (incident.io pattern)
+- **Orchestrates SYNC/ASYNC** (line 72-80): Dependency-aware scheduling enables safe parallel execution of mixed SYNC/ASYNC tasks
+- **Prerequisite for Tier 1.3** (line 323-328): Worktree branch context becomes artifact delivery mechanism for remote async agents
+- **Realizes Tier 2.5** (line 407-413): This IS the implementation of "Parallel Sub-Agent Coordination" with explicit dependencies
+
+**Key Benefits**:
+
+- Enables incident.io's 5+ agents in parallel without context clash (each in isolated branch + worktree)
+- Pre-merge hooks enforce dependency constraints before merging
+- Phase-respecting orchestration maintains logical workflow structure
+- Graceful fallback without Worktrunk (sequential in-directory execution)
+- Clear visibility into which tasks are blocked (waiting for dependencies)
+
+**Success Metrics**:
+
+- All 3 phases complete in correct order
+- Multiple [P] tasks execute simultaneously (with Worktrunk)
+- Pre-merge hooks prevent merging with unmet dependencies
+- Dashboard shows real-time parallel task progress
+- ASYNC tasks receive full worktree branch context (ready for Tier 1)
+
+**Risks & Mitigation**:
+
+| Risk | Mitigation |
+|------|-----------|
+| Dependency cycles in tasks.md | DAG validation in Phase 1 prevents cycles during parsing |
+| Pre-merge hooks too strict | Customizable per project in `.config/wt.toml` |
+| Worktrunk not installed | Graceful fallback to sequential in-directory execution |
+| Tasks blocked on dependencies | Clear warning messages indicate which deps are waiting |
+| Tier 1 integration complexity | Phase 4 provides scoped worktree context + packaging |
+
+**References**:
+
+- incident.io: "Shipping faster with Claude Code and Git Worktrees" (Jun 2025) - validates multi-agent + worktree pattern
+- Worktrunk: https://github.com/max-sixty/worktrunk - git worktree management for parallel AI workflows
+- Existing SYNC/ASYNC triage (line 72-87) + [P] markers (line 56-61) provide foundation
+
+---
+
 ### **Command Prefix Migration** *(0% Complete)* - **MEDIUM PRIORITY** - Fork differentiation and user experience
 
 - ❌ **Prefix Change Implementation**: Migrate from `/speckit.*` to `/agenticsdlc.*` commands for clear fork identification
@@ -519,6 +619,113 @@ Consolidates: Command-level model selection + context budgeting + two-model revi
 
 ### **Future Enhancement Categories**
 
+### **Beads-Backed Task Execution Tracker** *(0% Complete)* - **MEDIUM PRIORITY** - Agent-native persistent work tracking
+
+**Problem Statement**: 
+The `/tasks` command generates dependency-ordered tasks.md files, but agents lack persistent cross-session visibility into task state, dependencies, and execution progress. This leads to:
+- Agents losing context about task generation decisions across sessions (inter-session amnesia)
+- Inability to query ready-to-execute tasks without parsing markdown
+- Lost work discovery when agents encounter issues during implementation but lack structured recording mechanism
+- Suboptimal agent behavior near context limits (workarounds instead of updating task status)
+
+Per Steve Yegge's Beads manifesto, agents naturally work better with issue trackers than markdown plans because structured dependency queries and persistent memory solve these problems.
+
+**Solution**: 
+Integrate Beads (native issue tracker) with `/tasks` command as dual-output system:
+- `/tasks` continues generating tasks.md (no breaking changes to current workflow)
+- **NEW**: `/tasks` also populates beads issues with explicit dependencies, SYNC/ASYNC classification, and phase structure
+- Agents can query beads during `/implement` for ready work: `bd ready --json --assignee me`
+- Discovered work automatically recorded to beads by agents without context pressure
+- Task status updates via `bd update` provide persistent progress tracking across sessions
+
+**Scope** (Conservative Approach - Option A):
+- ✅ `/tasks` generates beads issues in parallel with tasks.md (coexistence, not replacement)
+- ✅ Each task becomes a beads issue with:
+  - Title: Task name from tasks.md
+  - Description: Task description + rationale for SYNC/ASYNC classification
+  - Labels: `[SYNC]`, `[ASYNC]`, `[P]` (parallelizable), phase name (Setup, Foundational, US1, etc.)
+  - Dependencies: Links between phases and dependent tasks via beads parent/child relationships
+  - Status: `open` (not started), `in_progress`, `done`
+- ✅ Beads database lives alongside tasks.md in `specs/[feature-name]/` directory
+- ✅ Beads is native install (users install `bd` CLI separately)
+- ✅ Graceful fallback: If beads unavailable, tasks.md workflow still works
+- ❌ NOT replacing tasks.md as execution format (yet)
+- ❌ NOT for multi-feature pattern learning
+- ❌ NOT for cross-project agent coordination
+
+**Integration Points**:
+
+| Component | Current | Change | Impact |
+|-----------|---------|--------|--------|
+| `/tasks` command | Generates tasks.md only | Also calls `bd create` for each task | Dual output, no breaking changes |
+| `tasks-meta-utils.sh` | Tracks task metadata in tasks_meta.json | Sync SYNC/ASYNC classification to beads issue labels | Beads becomes single source of execution mode truth |
+| `/implement` command | Parses tasks.md for task list | Optional: Query `bd ready --json` for better structure (Phase 2) | Phase 1 uses tasks.md, Phase 2 uses beads |
+| Task storage | `specs/[feature]/tasks.md` | Add `specs/[feature]/.beads/` directory | Beads provides query-able execution tracker |
+| Agent context | Session-based (limited memory) | Can query beads for discovered issues, previous decisions | Persistent cross-session memory |
+
+**Implementation Roadmap**:
+
+**Phase 1: Beads Issue Generation from `/tasks`** (Weeks 1-3)
+- ❌ Modify `/tasks` template to call `scripts/bash/tasks-to-beads.sh` after tasks.md generation
+- ❌ Create `scripts/bash/tasks-to-beads.sh` (+ PowerShell equivalent):
+  - Parse generated tasks.md 
+  - Extract: task ID, title, description, phase, SYNC/ASYNC classification, dependencies
+  - Call `bd create` with formatted issue + labels
+  - Link parent/child tasks via beads dependency relationships
+  - Handle duplicate runs (update existing issues vs. create new)
+- ❌ Add beads initialization to `/tasks` workflow: `bd init` if `.beads/` doesn't exist
+- ❌ Document beads setup in `/tasks` help text: "Beads database available at .beads/issues.jsonl"
+- ❌ Test with single feature: Generate tasks.md + beads issues, verify structure
+
+**Phase 2: Agent Work Discovery & Status Tracking** (Weeks 4-6, deferred)
+- ❌ Guide agents to use `bd create` when discovering issues during implementation
+- ❌ Inject prompt guidance into `/implement` delegation template about recording work
+- ❌ Enable agents to update task status: `bd update --status in_progress` as they work
+- ❌ Test: Run `/implement` with beads tracking, verify discovered issues recorded
+
+**Phase 3: Query-Based Task Fetching** (Weeks 7-9, deferred - Option B migration)
+- ❌ Modify `/implement` to use `bd ready --json` instead of parsing tasks.md
+- ❌ Implement task batching: agents fetch tasks in phases (Setup → Foundational → Stories)
+- ❌ Enable dynamic task re-ordering based on discovered blockers (via beads dependency updates)
+- ❌ This phase represents migration from Option A (coexistence) to Option B (full beads execution)
+
+**Relationship to Async Work** (Tier 1.4 - Tier 1.6):
+- Beads issues can be tagged `async-ready` during `/tasks` generation (integrates with Tier 1.5)
+- Remote async agents query `bd ready --json --label async-ready` for delegatable work
+- Webhook callbacks from remote agents update beads issue status (Tier 1.4)
+- Full artifact context packaging (Tier 1.6) includes beads issue descriptions for agent briefing
+
+**Success Metrics**:
+- Phase 1 Complete: 100% of tasks.md tasks also exist as beads issues with correct dependencies
+- Phase 1 Quality: Agents report improved context retention across `/tasks` regenerations
+- Phase 2 Complete: Discovered issues automatically recorded to beads (no manual prompting)
+- Phase 3 Complete: Agents prefer `bd ready --json` queries over tasks.md parsing
+
+**Risks & Mitigation**:
+- Risk: Agents delete/corrupt beads database (like markdown plans in Yegge's experience)
+  - Mitigation: Beads backed by git, easy recovery; document git workflow in guide
+- Risk: Tasks.md and beads get out of sync during development
+  - Mitigation: Phase 1 only generates beads at `/tasks` time; `/implement` still uses tasks.md (Phase 3 solves this)
+- Risk: Beads adoption overhead for users
+  - Mitigation: Optional feature (graceful fallback); native beads install keeps dependencies simple
+
+**Related Commands**:
+- Complements `/trace` command (which captures session decisions) by making them queryable
+- Enables future `/levelup` enhancements (extract patterns from beads issue history)
+- Works with existing `/implement` (Phase 1) and enhances it (Phase 2-3)
+
+**References**:
+- Beads Article: https://steve-yegge.medium.com/introducing-beads-a-coding-agent-memory-system-637d7d92514a
+- Beads GitHub: https://github.com/steveyegge/beads
+
+**Notes**:
+- Conservative scope (Option A) chosen to minimize risk: coexists with tasks.md, no breaking changes
+- Full vision (Option B) available for future consideration: agents work directly from beads queries
+- Implementation depends on users having `bd` CLI installed (documentation will cover setup)
+- Aligns with Beads manifesto insight: agents work better with persistent, queryable issue trackers than stateless markdown
+
+---
+
 ### **Executable Specifications** *(0% Complete)* - **NICE-TO-HAVE** - No implementation planned
 
 **Status**: Deferred to focus on core workflow stability and high-priority items.

scripts/bash/common.sh

@@ -409,10 +409,25 @@ try:
     
     print(json.dumps(views, ensure_ascii=False))
 except Exception as e:
-    print('{}')
+    print('[]')
 PY
 }
 
+# Detect workflow mode and framework options from spec.md
+# Usage: detect_workflow_config [path/to/spec.md]
+# Returns JSON: {"mode":"build|spec","tdd":true|false,"contracts":true|false,"data_models":true|false,"risk_tests":true|false}
+detect_workflow_config() {
+    local spec_file="${1:-spec.md}"
+    
+    # Source the standalone script
+    local script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    source "$script_dir/detect-workflow-config.sh"
+    
+    # Call the function
+    detect_workflow_config "$spec_file"
+}
+
+
 # Extract diagram blocks from architecture.md
 # Returns JSON array of diagrams with type and format
 extract_architecture_diagrams() {