Execute

Implementation methodology. Loads alongside the domain skill (e.g., "noodle") — this teaches process, the domain skill teaches the codebase.

Operate fully autonomously. Never ask the user. Don't stop until the work is fully complete.

Track all work with Tasks (TaskCreate, TaskUpdate, TaskList). One task per decomposed change; mark in_progress when starting, completed when done.

Execution Flow

1. Scope

Establish what needs doing:

• Plan phase: Read the assigned phase from brain/plans/. Read the overview for scope boundaries. Invoke Skill(backlog) for project-specific context. Load domain skills listed in "Applicable skills."
• Backlog item: Read the todo from brain/todos.md. If a linked plan exists, read it. Otherwise, scope from the description.
• Ad-hoc request: The user prompt is the scope. Identify affected files and packages before starting.

Output: a clear, bounded description of what changes and what doesn't.

2. Decompose

Break scope into discrete changes. Each change:

• One function/type + its tests, OR one bug fix
• Independently compilable
• One conventional commit

Single-change scopes skip decomposition.

3. Implement

Worktree First — Non-Negotiable

Never edit files on main. Multiple sessions run concurrently; editing main causes merge conflicts and lost work.

If CWD is already inside .worktrees/, use it. Otherwise: noodle worktree create <descriptive-name>

Use absolute paths or noodle worktree exec <name> <cmd>. Never cd into a worktree — if it gets removed while the shell is inside, the session dies permanently.

Commit inside the worktree. When done: noodle worktree merge <name>

Skip only when the user is interactively driving a single-agent session and explicitly chooses main.

Delegation

• Self-execute: Single change, or tightly coupled changes (shared types, sequential dependencies).
• Sub-agents: 2+ independent changes touching different files. Front-load context: scope, relevant code, domain skill name.
• Team execution: 2+ parallelizable phases in a plan. See below.
• Codex: Mechanical work not requiring judgment (renames, boilerplate, repetitive edits). Never for architectural decisions.

Sequential is fine when phases are tightly coupled. Before parallelizing, ask: "Does any phase's output become another phase's input?" If one phase defines a type/interface that another consumes, they share an API contract and must be sequential — otherwise each invents its own version. Only phases with no type-level coupling can overlap.

Team Execution

The lead orchestrates — it does NOT implement. Research via sub-agents, delegate all implementation to teammates.

1. Lead worktree: Use current worktree if already in one, otherwise noodle worktree create plan-<N>-lead
2. Team: TeamCreate — all tasks go through this team's task list
3. Per-teammate worktrees: noodle worktree create plan-<N>-phase-<M>
4. Spawn teammates: Task with mode: "bypassPermissions", team_name, worktree path, scope, and domain skill name. Always spawn fresh agents to keep context clean.
5. Teammates commit on their own branches
6. Review before merging: Spawn a review agent to check each teammate's work against the plan before merging
7. Merge teammates into lead (not main):

   git -C .worktrees/plan-<N>-lead merge <teammate-branch>
   noodle worktree cleanup plan-<N>-phase-<M>
   

8. Verify integrated result in lead worktree (see Verify below)
9. Merge lead to main: noodle worktree merge plan-<N>-lead

Foundational phases that later phases depend on: execute first, commit in lead worktree, then create teammate worktrees from that point.

4. Verify

Every change must pass before committing. Fix and re-verify on failure. Never commit failing code.

Unit & static analysis — after each change:

• go test ./... (or scoped to changed packages)
• go vet ./...
• sh scripts/lint-arch.sh — if present

E2E smoke tests — after integrating changes, before merging to main:

• pnpm test:smoke
• In a worktree: noodle worktree exec <name> pnpm test:smoke
• When UI changes: write NEW test cases covering the changed interface

Fixture tests — when changes affect loop behavior or runtime state:

• pnpm fixtures:loop / pnpm fixtures:hash
• Update fixtures: pnpm fixtures:loop:record then pnpm fixtures:hash:sync

Visual verification — when changes affect UI:

• Use the Chrome tool to open the UI in browser, click through affected flows

Scope check:

• git diff --stat — matches expected scope
• All checklist items addressed (plan phase, todo criteria, or ad-hoc requirements)

5. Commit

<type>(<scope>): <description>

Refs: #<issue-ID>

Types: feat, fix, refactor, test, docs, chore. Scope: package or area changed. Refs: include when linked issue exists; omit for ad-hoc work.

One commit per logical change.

6. Yield

After all changes are committed and verified, emit stage_yield to signal the deliverable is complete:

noodle event emit --session $NOODLE_SESSION_ID stage_yield --payload '{"message": "Implemented: <brief summary>"}'

This tells the Noodle backend the stage's work is done, even if the agent process hasn't exited yet. Without this, the stage only completes on clean process exit — if the agent is interrupted after committing, the work is lost to the pipeline.

Scope Discipline

• Only change what's in scope. No defensive code, backwards-compat shims, or speculative features.
• Out-of-scope discoveries go in the quality review notes — don't change them.
• Wrong or incomplete plan/requirements: flag it in output, don't silently deviate.

Principles

Read at runtime from brain/principles/:

• [[prove-it-works]]
• [[subtract-before-you-add]]
• [[cost-aware-delegation]]
• [[guard-the-context-window]]
• [[boundary-discipline]]
• [[outcome-oriented-execution]]