Feature Execution Assistant (Idea-Scoped, Tasks-Driven)

Execute development iteratively using Features (FEAT-XXX) as the unit of work.

This command must NOT depend on

latest/work_packages.md

. The canonical source of truth is the feature-grouped tasks in:

• docs/forge/ideas/<IDEA_ID>/latest/tasks.md

Supports optional arguments:

• /work-feat IDEA-0002-my-idea

  -> auto-pick the next not-yet-completed FEAT from tasks.md using the progress tracker

• /work-feat IDEA-0002-my-idea FEAT-003

  -> execute a specific feature

• /work-feat FEAT-003

  -> best-effort: locate the FEAT by scanning idea tasks (only if unique)

Use

$ARGUMENTS

for IDEA_ID and/or FEAT id.

---

Resolve IDEA_ID (required)

Before using any idea-scoped paths:

• If

  $ARGUMENTS

  starts with

  IDEA-

  , treat the first token as

  IDEA_REF

  .
• Call

  vf.resolve_idea_id

  with

  idea_ref = IDEA_REF

  and store

  IDEA_ID

  .
• Use

  IDEA_ID

  for all paths, YAML headers, and run log entries.

---

Inputs (Auto)

Canonical sources of truth (idea-scoped)

• docs/forge/ideas/<IDEA_ID>/latest/tasks.md

  (required; feature-grouped task definitions)

• docs/forge/ideas/<IDEA_ID>/latest/existing_solution_map.md

  (context for existing code, update when necessary)

• docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md

  (broader project context)

Optional context

• docs/forge/ideas/<IDEA_ID>/latest/features_backlog.md

  (fallback to features.md if missing)

• docs/forge/ideas/<IDEA_ID>/latest/epics_backlog.md

  (fallback to epics.md if missing)

• docs/forge/ideas/<IDEA_ID>/latest/concept_summary.md

• docs/forge/ideas/<IDEA_ID>/latest/existing_solution_map.md

• docs/forge/ideas/<IDEA_ID>/latest/codebase_context.md

• docs/forge/ideas/<IDEA_ID>/inputs/idea.md

Execution tracking (small, per-idea)

• docs/forge/ideas/<IDEA_ID>/latest/feature_execution_progress.md

  (create if missing; append-only)

• docs/forge/ideas/<IDEA_ID>/planning/

  (workspace checklists live here)

• docs/forge/ideas/<IDEA_ID>/manifest.md

  (optional best-effort)

• docs/forge/ideas/<IDEA_ID>/run_log.md

  (append-only)

---

Step 0 - Safety & Repo Context

1. Read current repo state:

• git status -sb

• git diff --stat

2. If there are unrelated uncommitted changes:

• Ask the user to confirm whether to stash/commit before proceeding.
• Do NOT proceed blindly.

---

Step 1 - Determine target FEAT

Accepted invocation forms

Form A:

$ARGUMENTS

starts with

IDEA-...

• Parse:

  • IDEA_REF = first token

  • Optional

    FEAT_ID = second token

    if it matches

    FEAT-\d{3}

  • Resolve

    IDEA_ID

    using

    vf.resolve_idea_id

Form B:

$ARGUMENTS

is only

FEAT-XXX

• Scan all idea folders under

  docs/forge/ideas/

  for a

  latest/tasks.md

  containing that FEAT header.
• If exactly one match is found, set

  IDEA_ID

  accordingly.
• If zero matches: STOP and report "FEAT not found in any idea."
• If multiple matches: STOP and list candidates; ask the user to rerun with explicit

  IDEA_ID

  .

If no

FEAT_ID

was provided:

• Auto-select the next FEAT not marked complete in

  latest/feature_execution_progress.md

  .

IMPORTANT: Do not scan the entire tasks.md

When selecting or executing a feature:

• Use targeted search within

  latest/tasks.md

  to locate the FEAT section header (e.g.,

  FEAT-003:

  or

  ## FEAT-003

  ).
• Extract ONLY the tasks under that FEAT section.

If tasks.md format varies, adapt by finding a stable "feature header" pattern used in the file and extracting the block until the next feature header.

---

Step 2 - Confirm required files exist

Required:

• docs/forge/ideas/<IDEA_ID>/latest/tasks.md

Create if missing:

• docs/forge/ideas/<IDEA_ID>/latest/feature_execution_progress.md

• docs/forge/ideas/<IDEA_ID>/planning/

If

latest/tasks.md

is missing, STOP and report the expected path.

---

Step 3 - Build the Feature Workspace Checklist (short)

Create (or update) a checklist doc for this feature:

• docs/forge/ideas/<IDEA_ID>/planning/FEC-<FEAT_ID>-workspace-checklist.md

Checklist requirements (keep it short):

• Title:

  <FEAT_ID> - <feature title>

• Idea-ID and Run-ID
• A checkbox list of the tasks in this feature (TASK-### ids + titles)
• For each task: 1-2 bullets:
  • key files expected to change (from existing_solution_map if available; otherwise best-effort)
  • verify command(s) (best-effort)
• "Notes / Decisions" section (append-only)

Do NOT create long plan docs. This is a working checklist.

---

Step 4 - Mark Feature as In Progress (progress tracker)

Update

docs/forge/ideas/<IDEA_ID>/latest/feature_execution_progress.md

:

• If this FEAT is not present, add an entry:

  • FEAT-XXX - In Progress - <timestamp> - run <RUN_ID> - checklist: planning/FEC-FEAT-XXX-workspace-checklist.md

• If already present and In Progress, treat as resume.

---

Step 5 - Execute Tasks One at a Time (Iterative Loop)

For each TASK in the feature's section (in dependency order if stated; otherwise file order):

5.1 - Preparation

• Use

  existing_solution_map.md

  if present to prefer extension of existing code.
• Do minimal, focused changes.
• Keep commits small; include

  TASK-###

  in commit messages.

5.2 - Implement

• Implement the smallest change meeting acceptance criteria.
• Avoid parallel implementations; extend existing components where possible.

5.3 - Verify

• Run the most relevant verification (unit tests/lint/smoke).
• If failing: attempt focused fix; re-run.

5.4 - Update checklist

In

planning/FEC-...-workspace-checklist.md

:

• Check off the task only after verification passes.
• Add 1-3 bullets:
  • files changed
  • commands run
  • anything learned

5.5 - If blocked

• Record blocker under that task in the checklist
• Update progress tracker to

  Blocked

  for this FEAT
• STOP

---

Step 6 - Feature-level Close Out

After all tasks are checked:

1. Run a feature-level verification (best-effort):
   • run the main test suite subset relevant to changed areas
2. If passes:
   • Update progress tracker:

     FEAT-XXX - Done - <timestamp> - run <RUN_ID>

3. If fails:
   • Keep FEAT as In Progress
   • Record failure summary in checklist and STOP

---

Step 7 - End-of-Run Summary (Always)

Print a concise summary:

• Feature executed: FEAT-XXX
• Tasks done vs remaining
• Verification commands run + result
• Key files touched
• Next recommended feature (next not-done FEAT)

---

Required tool calls (MCP helpers)

• vf.start_run

  (idea_id=<IDEA_ID>, label="work-feat")

• vf.write

  to create/update:

  • planning/FEC-<FEAT_ID>-workspace-checklist.md

  • latest/feature_execution_progress.md

  • run snapshots under

    runs/<RUN_ID>/...

    (best-effort)

• vf.append_log

  with stage

  execute.feature

  and outputs

---

Non-negotiable Rules

• Source of truth is

  latest/tasks.md

  .
• Execute exactly one feature per invocation.
• Do not read the full tasks.md; extract only the FEAT section being executed.
• Prefer extending existing code over creating parallel subsystems (use existing_solution_map when available).
• Only mark tasks done after verification passes.