start

What this skill does

# Start — Lifecycle Orchestrator

Guide development work through the correct lifecycle steps, invoking the right skill at each stage. This is the single entry point for any non-trivial work.

**Announce at start:** "Starting the feature lifecycle. Analyzing your project to recommend the right tool..."

## Triage

Before brainstorming, analyze your project description to determine the correct path: **quick** (bounded trivial edit confirmed by code), **feature-flow** (standard lifecycle), or **GSD** (multi-feature project).

### Step 1: Check if tool selection is enabled

Read `.feature-flow.yml` and look for `tool_selector.enabled`:
- If `enabled: false` → skip tool selection, proceed directly to brainstorming
- If `enabled: true` or missing → continue to step 2

### Step 2: Check for command-line overrides

Did the user include `--feature-flow`, `--gsd`, or `--no-quick` flag?
- If `--feature-flow` present → remove flag from description, skip detection, use feature-flow
- If `--gsd` present → remove flag from description, skip detection, launch GSD
- If `--no-quick` present → remove flag from description, record `no_quick_override = true`, continue to step 3 (Quick-Path Confirmation will be skipped; heuristic scoring runs normally)
- If `--quick` or any other `--foo` token is present that is NOT in `--feature-flow` / `--gsd` / `--no-quick` → surface: *"Unknown flag `--foo`. Quick path is opt-out only (`--no-quick`); there is no `--quick` flag. Continuing with auto-detection."* Strip the token from description and continue to step 3.
- If no flags → continue to step 3

### Step 3: Quick-Path Confirmation

Quick path is available when `tool_selector.quick_path.enabled` is `true` (default) and `no_quick_override` is not set (see Step 2 — set by the `--no-quick` flag). If either condition is false, skip this step entirely and continue to Step 4.

Run gates in strict order 0 → 4. **First failure short-circuits immediately** — do not run later gates. Pass budget: **≤5 Bash/Grep/Read/Glob tool calls total across all gates**. In-process AST tokenization and byte-range overlap checks are free (do not count). If you reach 5 tool calls before all gates pass, abort confirmation and fall through silently.

Once a file is Read (1 budget call), Claude may reason over its contents freely for Gate 3 and Gate 4 without further cost — but *re-reading* the same file counts as an additional call.

| # | Gate | Pass condition | Fail surface |
|---|------|----------------|--------------|
| 0 | **Clean working tree** | `git status --porcelain` returns empty | Surface to user: *"Working tree is dirty — running normal lifecycle to avoid trampling in-progress work."* Then fall through to heuristic scoring. |
| 1 | **Concrete target identifiable** | Description names a file path, function name, symbol, or string literal | Surface to user: *"No specific target named — running normal lifecycle. If you meant a specific file, say `start: fix typo in X.ts line 42`."* Then fall through. |
| 2 | **Bounded file count** | Target resolves to ≤ `max_files` files (default 3) | Silent fallthrough |
| 3 | **No exported-declaration overlap** | The edit's byte range does not overlap any `export` / `export default` / `module.exports` AST node. Check is mechanical byte-range overlap — not a "flows outward" semantic analysis. Edits to the body of a re-exported internal symbol pass Gate 3 (byte range does not overlap the `export` node itself); Gate 4 catches such edits via identifier-position exclusion. | Silent fallthrough |
| 4 | **Lexical-region rule** | Every proposed `old_string` byte range sits entirely inside one of: **(a)** Markdown prose outside `` ``` `` fences; **(b)** a string literal node in a code file that is **not** a syntactic argument to a `log.*` / `logger.*` / `console.*` call expression (walk up to nearest `CallExpression` or `TaggedTemplateExpression`; if callee root identifier matches case-insensitively, fail); **(c)** a line or block comment node. Identifiers, keywords, imports, type annotations, decorators, numeric/boolean literals, operators always fail. Unsupported languages (not Markdown/TypeScript/JavaScript/Python) conservatively fail. Multiple `old_string` ranges: all must pass individually. | Silent fallthrough |

**Gate 4 log-call exclusion detail:** From the matched string-literal node, walk up to the nearest enclosing `CallExpression` or `TaggedTemplateExpression`. Resolve the callee to its **root identifier** (the leftmost name in `a.b.c.d(...)` is `a`; for `this.x.y(...)`, the root is `this` — in which case look one level in: `x`). If the root identifier (case-insensitive) is exactly `log`, `logger`, or `console` → Gate 4 **fails**. Does NOT match `logging` (Python stdlib) — Python's `logging` module is a separate exclusion documented under Gate 4 edge cases below.

**Python `logging.*` exclusion:** Python `logging.*` calls (e.g. `logging.info(...)`, `logging.warning(...)`) are also excluded via the same CallExpression ancestor walk — if the root identifier case-insensitively equals `logging`, Gate 4 fails.

**Gate 4 whitespace tolerance:** If a proposed `old_string` region, extended by leading/trailing whitespace to the nearest non-whitespace character, would cross out of the confirmed lexical region, Gate 4 **fails** (fail-closed).

**Edge cases — Gate 4 fails when in doubt.** The following all fail Gate 4 regardless of surface appearance: (a) TypeScript type-position string literals (`const x: "foo" = ...` — the first `"foo"` is a type, not a value); (b) expressions inside f-strings / template literals (`f"hello {user.name}"`, `` `hello ${user.name}` `` — the `{user.name}` / `${user.name}` region is an expression, not string content); (c) JSX attribute values that are identifiers or expressions rather than string literals; (d) any string-like syntax Claude cannot confidently classify to an AST node kind in a single pass. When the region kind is not unambiguously string-literal / comment / MD-prose, Gate 4 fails.

**Budget exhaustion:** If the 5-tool-call budget is reached before all gates finish evaluating, silently fall through to heuristic scoring. The change is not quick by definition.

**On all-pass:** Set `quick_path_confirmed = true`. Record confirmed scope: the set of file paths and their confirmed lexical regions (held in working context only — no state file). Jump to Step 7 quick-path execution branch.

**On any fail or skip:** Continue to Step 4.

---

### Step 4: Run heuristic detection

Analyze user's project description using heuristics:
1. Extract feature count (using regex for action verbs)
2. Check for scope keywords ("from scratch", "complete app", etc.)
3. Parse timeline mentions ("hours" vs "weeks/months")
4. Detect complexity patterns (multiple stacks, microservices, explicit counts)

Calculate weighted confidence score (0.0–1.0) using scoring table.

### Step 5: Check confidence threshold

**If `quick_path_confirmed` is set** (from Step 3), skip this step entirely and proceed to Step 6. Confidence threshold applies only to the heuristic-scoring path.

Read `tool_selector.confidence_threshold` from .feature-flow.yml (default: 0.7):
- If calculated_confidence < threshold → skip recommendation, proceed with feature-flow
- If calculated_confidence >= threshold → continue to step 6

### Step 6: Display recommendation

Show recommendation based on path or confidence band:

- **⚡ quick path** — reached only via Quick-Path Confirmation gates (Step 3), never via heuristic scoring. Emit the announcement line HERE, immediately before Step 7 begins. Announce in a single auditable line before making any edits:
  ```
  ⚡ Quick path confirmed: <path>:<line> — <region kind> in <language>, <N> file(s), budget: ≤<max_changed_lines> lines. Editing directly.
  ```
  Where `<region kind>` is one of: `prose edit in Markdown`, `comment edit in TypeScript`, `string-literal edit in Python`, etc. `<max_changed_lines>` is the configured cap, not the actual diff