feat: separate orchestrator directive from agent tasks

- IMPLEMENTATION_PLAN.md now contains single meta-directive: "Check .context/TASKS.md"
- Tasks live in agent's mind (.context/TASKS.md), not orchestrator
- ctx init creates IMPLEMENTATION_PLAN.md in project root
- PROMPT.md updated to check .context/TASKS.md for task selection
- Removed unused root templates/ directory (internal/templates/ is source of truth)
- Added decision record and learnings for orchestrator/agent separation
- Marked "Claude hooks" task complete in TASKS.md

Signed-off-by: Jose Alekhinne <alekhinejose@gmail.com>

Author: josealekhine

.context/DECISIONS.md

@@ -171,3 +171,30 @@ ctx init    # Creates BOTH .context/ AND .claude/hooks/
 - Only works with Claude Code (other tools need different approach)
 - Requires jq for JSON parsing in hook script
 - Session files are .jsonl format (need tooling to read)
+
+---
+
+## [2025-01-21] Separate Orchestrator Directive from Agent Tasks
+
+**Status**: Accepted
+
+**Context**: Two task systems existed: `IMPLEMENTATION_PLAN.md` (Ralph Loop orchestrator) and `.context/TASKS.md` (ctx's own context). Ralph would find IMPLEMENTATION_PLAN.md complete and exit, ignoring .context/TASKS.md.
+
+**Decision**: Clean separation of concerns:
+- **`.context/TASKS.md`** = Agent's mind. Tasks the agent decided need doing.
+- **`IMPLEMENTATION_PLAN.md`** = Orchestrator's directive. A single meta-task: "Check your tasks."
+
+The orchestrator doesn't maintain a parallel ledger — it just tells the agent to check its own mind.
+
+**Rationale**:
+- Agent autonomy: the agent owns its task list
+- Single source of truth for tasks
+- Orchestrator is minimal, not a micromanager
+- Fresh `ctx init` deployments can have one directive: "Check .context/TASKS.md"
+- Prevents task list drift between two files
+
+**Consequences**:
+- `PROMPT.md` now references `.context/TASKS.md` for task selection
+- `IMPLEMENTATION_PLAN.md` becomes a thin directive layer
+- Historical milestones are archived, not active tasks
+- North Star goals live in IMPLEMENTATION_PLAN.md (meta-level, not tasks)

.context/LEARNINGS.md

@@ -129,3 +129,35 @@ The `.context/` directory is an ctx convention. Claude won't know about it unles
 CGO_ENABLED=0 go build -o ctx ./cmd/ctx
 CGO_ENABLED=0 go test ./...
 ```
+
+---
+
+## Project Structure
+
+### One Templates Directory, Not Two
+**Discovered**: 2025-01-21
+
+**Context**: Confusion arose about `templates/` (root) vs `internal/templates/` (embedded).
+
+**Lesson**: Only `internal/templates/` matters — it's where Go embeds files into the binary. A root `templates/` directory is spec baggage that serves no purpose.
+
+**The actual flow:**
+```
+internal/templates/  ──[ctx init]──>  .context/
+     (baked into binary)              (agent's working copy)
+```
+
+**Application**: Don't create duplicate template directories. One source of truth.
+
+### Orchestrator vs Agent Tasks
+**Discovered**: 2025-01-21
+
+**Context**: Ralph Loop checked `IMPLEMENTATION_PLAN.md`, found all tasks done, exited — ignoring `.context/TASKS.md`.
+
+**Lesson**: Separate concerns:
+- **`IMPLEMENTATION_PLAN.md`** = Orchestrator directive ("check your tasks")
+- **`.context/TASKS.md`** = Agent's mind (actual task list)
+
+The orchestrator shouldn't maintain a parallel ledger. It just says "check your mind."
+
+**Application**: For new projects, `IMPLEMENTATION_PLAN.md` has ONE task: "Check `.context/TASKS.md`"

.context/TASKS.md

@@ -4,13 +4,6 @@
 
 ## Next Up
 
-### Enhance `ctx init` to Create Claude Hooks `#priority:high` `#area:cli`
-- [ ] Embed hook scripts in binary (like templates)
-- [ ] Create `.claude/hooks/auto-save-session.sh` during init
-- [ ] Create `.claude/settings.local.json` with PreToolUse and SessionEnd hooks
-- [ ] Detect platform to set correct binary path in hooks
-- [ ] Update `ctx init` output to mention Claude Code integration
-
 ### Handle CLAUDE.md Creation/Merge `#priority:high` `#area:cli`
 - [ ] Create CLAUDE.md if it doesn't exist
 - [ ] If CLAUDE.md exists, backup to CLAUDE.md.<unix_timestamp>.bak before any modification
@@ -37,6 +30,7 @@
 
 ## Completed (Recent)
 
+- [x] Enhance `ctx init` to create Claude hooks (embedded scripts, settings.local.json, platform detection) — 2025-01-21
 - [x] Set up PreToolUse hook for auto-load — 2025-01-20
 - [x] Set up SessionEnd hook for auto-save — 2025-01-20
 - [x] Create `.context/sessions/` directory structure — 2025-01-20

IMPLEMENTATION_PLAN.md

@@ -1,45 +1,34 @@
 # Implementation Plan
 
-This file tracks the implementation progress for Active Memory CLI.
-
-## Milestone 1: Project Scaffolding
-- [x] Initialize Go module and directory structure
-- [x] Create Cobra CLI skeleton in `cmd/ctx/main.go`
-- [x] Create embedded templates in `internal/templates/`
-- [x] Add all template files to `templates/` directory
-
-## Milestone 2: Core Commands (MVP)
-- [x] Implement `ctx init` — Create `.context/` with template files
-- [x] Implement `ctx status` — Show context summary with token estimate
-- [x] Implement `ctx load` — Output assembled context markdown
-
-## Milestone 3: Context Operations
-- [x] Implement `ctx add` — Add decision/task/learning/convention
-- [x] Implement `ctx complete` — Mark task as done
-- [x] Implement `ctx agent` — Print AI-ready context packet
-
-## Milestone 4: Maintenance Commands
-- [x] Implement `ctx drift` — Detect stale paths, broken refs (text output)
-- [x] Implement `ctx drift --json` — JSON output for automation
-- [x] Implement `ctx sync` — Reconcile context with codebase
-- [x] Implement `ctx compact` — Archive completed tasks
-- [x] Implement `ctx watch` — Watch for context-update commands
-
-## Milestone 5: Integration
-- [x] Implement `ctx hook` — Generate AI tool integration configs
-- [x] Add `--help` text for all commands
-- [x] Add `--version` flag with build-time version
-
-## Milestone 6: Testing & Release
-- [x] Write unit tests for `internal/context/` (loader, parser)
-- [x] Write unit tests for `internal/drift/` (detector)
-- [x] Write integration tests for CLI commands
-- [x] Create `scripts/build-all.sh` for cross-platform builds
-- [x] Create `.github/workflows/release.yml` for GitHub Actions
-- [x] Create `examples/demo/` with sample `.context/` directory
-- [x] Update README.md with installation and usage instructions
-
-## Notes
-
-- Build command: `CGO_ENABLED=0 go build -o ctx ./cmd/ctx`
-- CGO is disabled due to gcc cross-compilation issues on ARM64 Linux
+This file is the orchestrator's directive. The agent's actual tasks live in `.context/TASKS.md`.
+
+## Current Directive
+
+- [ ] Check `.context/TASKS.md` and work on the first unchecked item
+
+## Completion Criteria
+
+When `.context/TASKS.md` has no unchecked items in "Next Up", the directive is complete.
+
+## North Star (Endgame)
+
+Before declaring DONE, remind the user about these goals:
+
+1. **Dogfood ctx on itself** — nuke repo, `ctx init` fresh, Ralph-loop build
+2. **Sample project** — bootstrap a RESTful app from scratch using ctx
+3. **Real-world validation** — apply to `github.com/spiffe/spike` and `spike-sdk-go`
+
+---
+
+## Archive (Historical)
+
+The following milestones were completed during initial development:
+
+### Milestone 1: Project Scaffolding ✅
+### Milestone 2: Core Commands (MVP) ✅
+### Milestone 3: Context Operations ✅
+### Milestone 4: Maintenance Commands ✅
+### Milestone 5: Integration ✅
+### Milestone 6: Testing & Release ✅
+
+Build command: `CGO_ENABLED=0 go build -o ctx ./cmd/ctx`

PROMPT.md

@@ -56,49 +56,16 @@ Check if `go.mod` exists.
 
 ## PHASE 2: SELECT TASK
 
-Read `IMPLEMENTATION_PLAN.md` and pick the **first unchecked item**.
-
-**IF NO UNCHECKED ITEMS:** Output `<promise>DONE</promise>` and exit.
-
-**NOTE:** Task tracking is done in `IMPLEMENTATION_PLAN.md`, not here.
-The milestones below are for reference only when creating a new plan.
-
-### Milestone 1: Project Scaffolding
-- Initialize Go module and directory structure
-- Create Cobra CLI skeleton in `cmd/ctx/main.go`
-- Create embedded templates in `internal/templates/`
-- Add all template files to `templates/` directory
-
-### Milestone 2: Core Commands (MVP)
-- Implement `ctx init` — Create `.context/` with template files
-- Implement `ctx status` — Show context summary with token estimate
-- Implement `ctx load` — Output assembled context markdown
-
-### Milestone 3: Context Operations
-- Implement `ctx add` — Add decision/task/learning/convention
-- Implement `ctx complete` — Mark task as done
-- Implement `ctx agent` — Print AI-ready context packet
-
-### Milestone 4: Maintenance Commands
-- Implement `ctx drift` — Detect stale paths, broken refs (text output)
-- Implement `ctx drift --json` — JSON output for automation
-- Implement `ctx sync` — Reconcile context with codebase
-- Implement `ctx compact` — Archive completed tasks
-- Implement `ctx watch` — Watch for context-update commands
-
-### Milestone 5: Integration
-- Implement `ctx hook` — Generate AI tool integration configs
-- Add `--help` text for all commands
-- Add `--version` flag with build-time version
-
-### Milestone 6: Testing & Release
-- Write unit tests for `internal/context/` (loader, parser)
-- Write unit tests for `internal/drift/` (detector)
-- Write integration tests for CLI commands
-- Create `scripts/build-all.sh` for cross-platform builds
-- Create `.github/workflows/release.yml` for GitHub Actions
-- Create `examples/demo/` with sample `.context/` directory
-- Update README.md with installation and usage instructions
+1. Read `IMPLEMENTATION_PLAN.md` for the current directive
+2. Follow the directive — typically: "Check `.context/TASKS.md`"
+3. Read `.context/TASKS.md` and pick the **first unchecked item** in "Next Up"
+
+**IF NO UNCHECKED ITEMS in `.context/TASKS.md`:**
+1. Check `IMPLEMENTATION_PLAN.md` for North Star goals
+2. Remind user about Endgame goals before exiting
+3. Output `<promise>DONE</promise>`
+
+**Philosophy:** Tasks live in the agent's mind (`.context/TASKS.md`). The orchestrator (`IMPLEMENTATION_PLAN.md`) provides the meta-directive, not the task list
 
 ---
 
@@ -134,10 +101,11 @@ go vet ./...            # No vet errors
 
 ## PHASE 5: UPDATE CONTEXT
 
-1. Mark completed task `[x]` in `IMPLEMENTATION_PLAN.md`
-2. If you made an architectural decision → document in `specs/` or `.context/DECISIONS.md`
-3. If you learned a gotcha → add to `.context/LEARNINGS.md`
-4. If build commands changed → update `AGENTS.md`
+1. Mark completed task `[x]` in `.context/TASKS.md`
+2. Move task to "Completed (Recent)" section with date
+3. If you made an architectural decision → document in `.context/DECISIONS.md`
+4. If you learned a gotcha → add to `.context/LEARNINGS.md`
+5. If build commands changed → update `AGENTS.md`
 
 ---
 
@@ -160,9 +128,9 @@ Complete ONE task, then stop. The loop handles continuation.
 
 ### NO CHAT
 Never ask questions. If blocked:
-1. Add `Blocked: [reason]` to `IMPLEMENTATION_PLAN.md`
-2. Move to next task
-3. If ALL blocked: `<promise>SYSTEM_BLOCKED</promise>`
+1. Move task to "Blocked" section in `.context/TASKS.md` with reason
+2. Move to next task in "Next Up"
+3. If ALL tasks blocked: `<promise>SYSTEM_BLOCKED</promise>`
 
 ### MEMORY IS THE FILESYSTEM
 You will not remember this conversation. Write everything important to files.
@@ -309,12 +277,10 @@ Never assume. If you don't see it in files, you don't know it.
 
 Output `<promise>DONE</promise>` ONLY when ALL of these are true:
 
-1. All commands in `specs/cli.md` are implemented
+1. `.context/TASKS.md` has no unchecked items in "Next Up"
 2. `go build ./...` passes
 3. `go test ./...` passes
-4. `ctx init && ctx status && ctx drift` works end-to-end
-5. `scripts/build-all.sh` produces binaries for linux/darwin/windows
-6. README.md has installation instructions
+4. You have reminded the user about the North Star goals in `IMPLEMENTATION_PLAN.md`
 
 ---
 

internal/cli/init.go

@@ -95,11 +95,16 @@ func runInit(cmd *cobra.Command, args []string) error {
 	if initMinimal {
 		templatesToCreate = minimalTemplates
 	} else {
-		var err error
-		templatesToCreate, err = templates.ListTemplates()
+		allTemplates, err := templates.ListTemplates()
 		if err != nil {
 			return fmt.Errorf("failed to list templates: %w", err)
 		}
+		// Filter out IMPLEMENTATION_PLAN.md - it goes in project root, not .context/
+		for _, t := range allTemplates {
+			if t != "IMPLEMENTATION_PLAN.md" {
+				templatesToCreate = append(templatesToCreate, t)
+			}
+		}
 	}
 
 	// Create template files
@@ -127,6 +132,12 @@ func runInit(cmd *cobra.Command, args []string) error {
 
 	fmt.Printf("\n%s initialized in %s/\n", green("Active Memory"), contextDir)
 
+	// Create IMPLEMENTATION_PLAN.md in project root (orchestrator directive)
+	if err := createImplementationPlan(initForce); err != nil {
+		// Non-fatal: warn but continue
+		fmt.Printf("  %s IMPLEMENTATION_PLAN.md: %v\n", color.YellowString("⚠"), err)
+	}
+
 	// Create Claude Code hooks
 	fmt.Println("\nSetting up Claude Code integration...")
 	if err := createClaudeHooks(initForce); err != nil {
@@ -249,3 +260,31 @@ func mergeSettingsHooks(projectDir string, force bool) error {
 
 	return nil
 }
+
+// createImplementationPlan creates IMPLEMENTATION_PLAN.md in project root
+// This is the orchestrator directive that points to .context/TASKS.md
+func createImplementationPlan(force bool) error {
+	green := color.New(color.FgGreen).SprintFunc()
+	yellow := color.New(color.FgYellow).SprintFunc()
+
+	const planFileName = "IMPLEMENTATION_PLAN.md"
+
+	// Check if file exists
+	if _, err := os.Stat(planFileName); err == nil && !force {
+		fmt.Printf("  %s %s (exists, skipped)\n", yellow("○"), planFileName)
+		return nil
+	}
+
+	// Get template content
+	content, err := templates.GetTemplate(planFileName)
+	if err != nil {
+		return fmt.Errorf("failed to read template: %w", err)
+	}
+
+	if err := os.WriteFile(planFileName, content, 0644); err != nil {
+		return fmt.Errorf("failed to write file: %w", err)
+	}
+
+	fmt.Printf("  %s %s (orchestrator directive)\n", green("✓"), planFileName)
+	return nil
+}

internal/templates/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,27 @@
+# Implementation Plan
+
+This file is the orchestrator's directive. The agent's actual tasks live in `.context/TASKS.md`.
+
+## Current Directive
+
+- [ ] Check `.context/TASKS.md` and work on the first unchecked item
+
+## Completion Criteria
+
+When `.context/TASKS.md` has no unchecked items in "Next Up", the directive is complete.
+
+## North Star (Endgame)
+
+Before declaring DONE, consider these goals:
+
+1. **Define your north star** — What does "done" look like for this project?
+2. **Validate end-to-end** — Does the system work as intended?
+3. **Document for others** — Can someone else pick this up?
+
+---
+
+## Notes
+
+- Tasks belong in `.context/TASKS.md` (the agent's mind)
+- This file provides meta-direction, not task details
+- Update North Star goals as the project evolves