✨ Orchestrated implementation, full-suite gate, archive fix

.github/workflows/actions.yml

@@ -21,3 +21,6 @@ jobs:
 
       - name: Test update settings script
         run: ./tests/test_update_settings.sh
+
+      - name: Test setup script
+        run: ./tests/test_setup_script.sh

docs/contributing.md

@@ -41,27 +41,27 @@ lead-dev-os/                          # The plugin
 
 ## Testing
 
-Tests live in `tests/` and cover both the plugin structure and legacy install behavior.
-
-### Run all tests
+Tests live in `tests/`. Each suite is a standalone bash script; run them individually:
 
 ```bash
-./tests/run_all.sh
+bash tests/test_plugin_structure.sh
+bash tests/test_skill_content.sh
+bash tests/test_content_bundle.sh
+bash tests/test_update_settings.sh
+bash tests/test_setup_script.sh
 ```
 
+CI (`.github/workflows/actions.yml`) runs all suites on every push.
+
 ### Test suites
 
 | Suite | File | What it tests |
 |-------|------|---------------|
-| Plugin structure | `tests/test_plugin_structure.sh` | plugin.json valid, all 9 skill dirs exist, configure-project skill has bundled standards |
-| Skill content | `tests/test_skill_content.sh` | No placeholders, all cross-refs namespaced, no config.yml refs, valid frontmatter |
+| Plugin structure | `tests/test_plugin_structure.sh` | plugin.json valid, all 9 skill dirs exist, flat layout, executable scripts |
+| Skill content | `tests/test_skill_content.sh` | No placeholders, cross-refs namespaced, valid frontmatter, planning content placement, orchestrated execution and full-suite gate present |
 | Content bundle | `tests/test_content_bundle.sh` | All global standards present, CLAUDE.md namespaced, README updated |
-| Update settings | `tests/test_update_settings.sh` | update-settings.sh creates/appends deny rules, idempotent |
-| Unit | `tests/test_common_functions.sh` | `ensure_dir`, `ensure_gitkeep`, `copy_if_not_exists`, `copy_with_warning`, `print_verbose` |
-| Integration: creates | `tests/test_install_creates.sh` | Fresh install produces all expected files (legacy installer) |
-| Integration: overwrites | `tests/test_install_overwrites.sh` | Re-install overwrites skills/guides, preserves concepts/standards (legacy installer) |
-| Integration: help | `tests/test_install_help.sh` | --help flag behavior (legacy installer) |
-| Integration: stack config | `tests/test_stack_config.sh` | Stack config, profiles, plan mode (legacy installer) |
+| Update settings | `tests/test_update_settings.sh` | update-settings.sh writes the archive deny rule under `permissions.deny`, migrates the legacy top-level rule, idempotent |
+| Setup script | `tests/test_setup_script.sh` | configure-project's setup.sh scaffolds directories, copies standards, renders templates, handles `--stacks`/`--overwrite` |
 
 ### Conventions
 

docs/implementation.md

@@ -16,11 +16,14 @@ Three execution modes control how much human oversight the AI receives during im
 
 ## Mode A: Autonomous
 
-All tasks execute sequentially with no human intervention. The agent loads context, implements each task, runs tests, and auto-commits after each one.
+All task groups are pre-planned in parallel (one planner subagent per group produces `plans/group-N.md`), you approve the batch, then execution runs with no human intervention. The main conversation acts as an **orchestrator**: each group is executed by a fresh executor subagent with a clean context, and the orchestrator verifies the group's tests itself, reviews the diff, and commits — one atomic commit per group. Independent groups (no dependency between them, disjoint file operations) may execute in parallel.
 
 ```
-T1 → T2 → T3 → T4 → T5 → DONE
-         (auto-commit after each task)
+        plan G1..G4 (parallel) → approve batch
+G1 ⇒ executor → verify → commit
+G2 ⇒ executor → verify → commit     (G2 ∥ G3 if independent)
+G3 ⇒ executor → verify → commit
+G4 ⇒ executor → verify → commit → DONE
 ```
 
 **Best for:** Small features, well-understood domains, no unknowns in the spec. The spec and task definitions are clear enough that the agent can ship without review.
@@ -29,10 +32,10 @@ T1 → T2 → T3 → T4 → T5 → DONE
 
 ## Mode L: Lead-in-the-Loop
 
-The agent implements one task, then pauses and waits for the lead developer to review before continuing. This creates a feedback loop at every task boundary.
+The agent plans and implements one task group in the main conversation (using Claude Code's native plan mode per group), then pauses and waits for the lead developer to review before continuing. This creates a feedback loop at every group boundary — and keeps the work visible, which is why L mode does not delegate to subagents.
 
 ```
-T1 → [REVIEW] → T2 → [REVIEW] → T3 → [REVIEW] → T4
+G1 → [REVIEW] → G2 → [REVIEW] → G3 → [REVIEW] → G4
          ↑                ↑                ↑
       lead reviews     lead reviews     lead reviews
 ```
@@ -51,10 +54,10 @@ At each review gate, the lead can:
 
 ## Mode H: Hybrid
 
-Implementation starts in autonomous mode and switches to lead-in-the-loop at a defined checkpoint. The lead specifies which task group triggers the handoff.
+Implementation starts in autonomous mode (orchestrator + executor subagents, as in Mode A) and switches to lead-in-the-loop at a defined checkpoint. The lead specifies which task group triggers the handoff.
 
 ```
-T1 → T2 → T3 ── STOP ── T4 → [REVIEW] → T5 → [REVIEW] → T6
+G1 → G2 → G3 ── STOP ── G4 → [REVIEW] → G5 → [REVIEW] → G6
 |← autonomous →|        |←────── lead-in-the-loop ──────→|
 ```
 
@@ -74,10 +77,15 @@ The autonomous portion handles scaffolding, boilerplate, or well-defined setup t
 | Prototype / spike / throwaway | **Autonomous** |
 | Production feature with stakeholder scrutiny | **Lead-in-the-Loop** |
 
-When you run `/lead-dev-os:step3-implement-tasks`, the skill prompts you to select a mode (A / L / H) after loading the spec context. If you choose Hybrid, it also asks which task group number to use as the checkpoint.
+When you run `/lead-dev-os:step3-implement-tasks`, the skill reads the `> Size:` estimate from `spec.md` (written by step 1) and recommends a mode — Small→A, Medium→H, Large→L — then prompts you to select (A / L / H). You always decide. If you choose Hybrid, it also asks which task group number to use as the checkpoint.
 
 ---
 
 ## After Implementation
 
-Once all task groups are complete and the feature is shipped, run `/lead-dev-os:step4-archive-spec` to archive the completed spec. This moves it to `lead-dev-os/specs-archived/` and blocks agent access so stale specs don't get loaded in future sessions.
+Once all task groups are complete, the skill closes with two gates before suggesting archive:
+
+- **Full-suite backstop** — the entire test suite runs once (the only full-suite run in the workflow; per-group runs stay feature-scoped for fast feedback). New failures caused by the feature get fixed; pre-existing failures get reported, not fixed.
+- **Runtime verification** — the agent exercises the feature's primary user flow in the running app where feasible, because tests passing is not the same as the feature working.
+
+Then run `/lead-dev-os:step4-archive-spec` to archive the completed spec. This moves it to `lead-dev-os/specs-archived/` and adds a rule under `permissions.deny` in `.claude/settings.json` so stale specs don't get loaded in future sessions.

docs/index.md

@@ -60,8 +60,8 @@ See [Installation]({{ site.baseurl }}/installation) for full details.
 | Phase | Skill | What it does |
 |-------|---------|--------------|
 | Write | `/lead-dev-os:step1-write-spec` | Interactive Q&A + formalize into spec with numbered requirements (FR-###) |
-| Scope | `/lead-dev-os:step2-scope-tasks` | Break into task groups with context directives |
-| Implement | `/lead-dev-os:step3-implement-tasks` | Context-aware execution of task groups |
+| Scope | `/lead-dev-os:step2-scope-tasks` | Break into task groups (vertical slices or layers) with context directives |
+| Implement | `/lead-dev-os:step3-implement-tasks` | Orchestrated execution — executor subagents per group, full-suite backstop |
 | Archive | `/lead-dev-os:step4-archive-spec` | Archive completed spec and block agent access |
 | Utility | `/lead-dev-os:create-pr` | Open a GitHub PR for the current branch with a WHAT-focused description and emoji-prefixed title |
 

docs/workflow.md

@@ -33,15 +33,15 @@ Interactive Q&A session to gather requirements, then formalizes into a structure
 
 ### Step 2: Scope (`/lead-dev-os:step2-scope-tasks`)
 
-Breaks the spec into task groups with explicit context directives. Each task group declares which files from `agents-context/` to load before executing, and reads as a complete user story — a plain-language goal and "done when" definition that a non-technical stakeholder can understand and verify. Produces `tasks.md` with atomic, implementable work items.
+Breaks the spec into task groups with explicit context directives. Groups follow an explicit strategy recorded in `tasks.md`: **vertical slices** (preferred — each group a thin end-to-end increment that's demoable on its own and parallelizable during implementation) or **layers** (Database → API → Frontend, when the data model is the hard part). Each task group declares which files from `agents-context/` to load before executing, and reads as a complete user story — a plain-language goal and "done when" definition that a non-technical stakeholder can understand and verify. Produces `tasks.md` with atomic, implementable work items.
 
 ### Step 3: Implement (`/lead-dev-os:step3-implement-tasks`)
 
-Context-aware execution of task groups. The agent loads only the context it needs for each task group, implements the code, and runs tests. See [Implementation]({{ site.baseurl }}/implementation) for the three execution modes.
+Context-aware execution of task groups. In autonomous modes each group runs in a fresh executor subagent while the main conversation orchestrates, verifies, and commits; independent groups can run in parallel. Execution ends with a full-test-suite backstop and a runtime check of the feature's primary flow. See [Implementation]({{ site.baseurl }}/implementation) for the three execution modes.
 
 ### Step 4: Archive (`/lead-dev-os:step4-archive-spec`)
 
-After implementation is complete, archive the spec to keep the workspace clean. Moves the spec folder from `lead-dev-os/specs/` to `lead-dev-os/specs-archived/` and adds a deny rule to `.claude/settings.json` so the agent won't accidentally load stale specs in future sessions.
+After implementation is complete, archive the spec to keep the workspace clean. Moves the spec folder from `lead-dev-os/specs/` to `lead-dev-os/specs-archived/` and adds a rule under `permissions.deny` in `.claude/settings.json` so the agent won't accidentally load stale specs in future sessions.
 
 ---
 

lead-dev-os/skills/configure-project/SKILL.md

@@ -20,13 +20,13 @@ Check if any lead-dev-os artifacts already exist:
 - `lead-dev-os/specs/` directory
 - `CLAUDE.md` with `## lead-dev-os Framework` section
 
-If any exist, inform the user what was found and ask: **"Some lead-dev-os artifacts already exist. Should I skip existing files (preserve your changes) or overwrite them with fresh defaults?"**
+If any exist, inform the user what was found and ask: **"Some lead-dev-os artifacts already exist. Should I skip existing files (preserve your changes) or overwrite them with fresh defaults?"** Use the `AskUserQuestion` tool when available — two options: "Skip existing (Recommended)" and "Overwrite with defaults" — falling back to a plain-text question otherwise.
 
 Remember their choice — you will pass it to the setup script.
 
 ### Phase 2: Ask About Technology Stack
 
-Ask the user: **"What technology stacks does your project use? Select all that apply:"**
+Ask the user: **"What technology stacks does your project use? Select all that apply:"** Use the `AskUserQuestion` tool when available with `multiSelect: true` (one question per category below, or grouped sensibly); fall back to a plain-text list otherwise.
 
 Present these categories:
 - **Languages:** Python, Ruby, TypeScript, JavaScript

lead-dev-os/skills/configure-project/scripts/setup.sh

@@ -166,7 +166,12 @@ README_DEST="agents-context/README.md"
 if [[ -f "$README_DEST" && "$OVERWRITE" == false ]]; then
   SKIPPED_FILES+=("agents-context/README.md (already exists)")
 else
-  # Use bash parameter expansion for safe replacement (handles &, \, etc.)
+  # Use bash parameter expansion for safe replacement (handles &, \, etc.).
+  # bash 5.2 enables patsub_replacement by default, which expands & in the
+  # replacement to the matched pattern and would mangle names like "A & B";
+  # disable it. Quoting the replacement instead is not portable: bash 3.2
+  # (macOS default) keeps the inner quotes literally.
+  shopt -u patsub_replacement 2>/dev/null || true
   while IFS= read -r line || [[ -n "$line" ]]; do
     printf '%s\n' "${line//\{Project Name\}/$PROJECT_NAME}"
   done < "${TEMPLATES_DIR}/readme.md" > "$README_DEST"

lead-dev-os/skills/create-or-update-concepts/SKILL.md

@@ -109,7 +109,7 @@ For each remaining area, do a quick peek at package/config files to identify the
 
 **2b. Dispatch focused subagents per area, in parallel.**
 
-For each significant top-level area, dispatch a codebase-analysis subagent via the Task tool. **Launch them all in a single message so they execute in parallel** — do not dispatch serially.
+For each significant top-level area, dispatch a codebase-analysis subagent via the Agent tool. **Launch them all in a single message so they execute in parallel** — do not dispatch serially.
 
 Use this prompt template (fill in the area path and project root):
 
@@ -144,7 +144,7 @@ Also answer: what questions would an AI agent need answered before making
 changes here?
 ```
 
-**Subagent type:** prefer `Explore` (purpose-built for codebase exploration, read-only, bounded token usage). If `codebase-analyzer` is available it's an even better fit for deep per-area analysis. Fall back to `general-purpose` if neither is available.
+**Subagent type:** use `Explore` (built into Claude Code — purpose-built for codebase exploration, read-only, bounded token usage), falling back to `general-purpose` if unavailable. If the target project defines its own analysis agent (e.g. a `codebase-analyzer` under `.claude/agents/`), that's an even better fit for deep per-area analysis — but never assume one exists.
 
 Collect the reports. If any report is thin or obviously shallow (e.g. a `src/` with dozens of files summarized in one line), re-dispatch with a narrower prompt targeting the specific gap.
 

lead-dev-os/skills/step1-write-spec/SKILL.md

@@ -10,11 +10,7 @@ Interactively gather requirements for a new feature through structured Q&A, rese
 
 ## Instructions
 
-You are a senior product engineer conducting a requirements discovery session and writing a formal specification. Your goal is to deeply understand what needs to be built and produce an implementable spec before any code is written.
-
-## Planning
-**Use plan mode per task group when implementing** -- This will allow to further break down the task into sub-tasks and plan them out.
-**When using plan mode, always include a final plan step to return to this tasks.md and check off completed tasks** (per project CLAUDE.md rule).
+You are a senior product engineer conducting a requirements discovery session and writing a formal specification. Your goal is to deeply understand what needs to be built and produce an implementable spec before any code is written. This skill writes documents only — implementation planning happens later, in `/lead-dev-os:step3-implement-tasks`.
 
 ### Phase 1: Initialize
 
@@ -51,6 +47,8 @@ Before asking questions, silently research available project context to inform y
 
 3. **Concept-driven reusability scan** — The concept files you read describe existing patterns, conventions, and architectural decisions — and they reference source file paths. Use these to identify reusable code without blindly searching the entire codebase. Note any relevant concepts and the source paths they reference.
 
+4. **If the scan must go beyond what the README indexes** (sparse concepts, or the feature touches undocumented territory), dispatch a read-only `Explore` subagent (fall back to `general-purpose`) with a bounded prompt — "find existing patterns, components, or modules related to [feature domain]; report paths and one-line descriptions, under 300 words" — instead of scanning the codebase in this conversation. Requirements gathering should keep the main context for the user's answers, not file dumps.
+
 Use this context to ask smarter, more targeted questions in the next phase. Do NOT ask the user about things already documented in these files.
 
 ### Phase 3: Clarifying Questions (Round 1)
@@ -145,6 +143,8 @@ Assess the feature size based on everything gathered:
 - **Medium** — Multiple components, some data model changes, moderate integration
 - **Large** — Cross-cutting concerns, significant data model changes, many integration points, multiple user flows
 
+Record the estimate in the spec header — the `> Size:` line in `spec.md` — with a one-line rationale. `/lead-dev-os:step3-implement-tasks` reads it to recommend an execution mode.
+
 Tell the user:
 - "Requirements saved to `lead-dev-os/specs/YYYY-MM-DD-<spec-name>/planning/requirements.md`"
 - "Specification saved to `lead-dev-os/specs/YYYY-MM-DD-<spec-name>/spec.md`"

lead-dev-os/skills/step1-write-spec/examples/user-profile-feature.md

@@ -95,6 +95,7 @@
 > Spec ID: 2026-02-25-user-profile
 > Status: Draft
 > Date: 2026-02-25
+> Size: Medium — multiple components and an avatar upload flow, but no cross-cutting concerns
 
 ## Goal
 

lead-dev-os/skills/step1-write-spec/template.md

@@ -94,6 +94,7 @@
 > Spec ID: YYYY-MM-DD-<spec-name>
 > Status: Draft
 > Date: YYYY-MM-DD
+> Size: [Small | Medium | Large] — [one-line rationale]
 
 ## Goal