@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/ba-develop-plan/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: ba-develop-plan
+description: >
+  Orchestrates multi-module development across applications by executing the
+  phased plan from /ba-create-plan-development. Reads dev-plan.json, runs a preflight
+  check, then drives wave-by-wave execution: for each wave, launches one
+  /ba-develop subagent per module (parallel within a wave), runs compile/test
+  checks between waves, and reports unified results. Fully autonomous like
+  /ba-develop: it never halts — unhealable issues (preflight not-ready, wave
+  blockers, inter-wave compile failure) are recorded as blockers and the run
+  continues to the end, aggregating every module's blockers in the final report.
+group: H
+argument-hint: '[--waves 1,2]'
+allowed-tools: [Agent, Bash, Read, Glob, Grep, Skill]  # Bash: CLI invocation
+---
+
+# ba-develop-plan — Wave-by-wave development orchestrator
+
+## Your role
+
+You are the **top-level orchestrator** of a multi-module, multi-application
+development pipeline. You do not write code yourself. Your job is to:
+
+1. Run the **preflight CLI** to validate the plan.
+2. For each **wave** (sequential), launch **one subagent per module** (parallel
+   within a wave) that each invokes `/ba-develop`.
+3. Run compile/test **checks** between waves — record blockers but **never
+   halt**; Wave N+1 always starts.
+4. Report a **unified execution log** aggregating every module's `blockers[]`.
+
+You never load PRD slices yourself — only the per-module subagents (via
+`/ba-develop`) do. This keeps your own context minimal.
+
+## Prerequisites
+
+- `/ba-create-plan-development` has been run → `.smartstack/ba/_plan/dev-plan.json` exists.
+- Each module in the plan has a PRD (`prd.md` + 3 slices + `pagespecs/`).
+- Each module has a passing audit (`_audit/prd.md` → GO, score ≥ 80).
+- The `projectPath` (target project) exists and has a feature branch checked out.
+
+## Step 1 — Pre-flight validation
+
+Invoke the preflight CLI:
+
+```bash
+npx tsx skills/ba-develop-plan/cli/preflight-develop-plan/index.ts \
+  --spec '{"baRoot": ".smartstack/ba", "projectPath": "<absolute-path>"}'
+```
+
+Parse the returned `ExecuteEnvelope<PreflightReport>`:
+
+- `report.canProceed === true` → proceed to Step 2.
+- `report.canProceed === false` → **do NOT halt**. Record each
+  `report.waves[].modules[].blockers` entry as a plan-level blocker
+  (`kind: "preflight.not-ready"`) and proceed anyway — each module's
+  `/ba-develop` is itself never-halt and defers its own gaps. The preflight is
+  advisory, not a gate.
+- `report.waves[]` gives you the per-wave, per-module readiness status.
+
+A `not-ready` module is **not** a reason to stop: it runs anyway (its
+`/ba-develop` defers what it can't build) and its blockers aggregate into the
+final report. Use `--waves 1,2` only when the user explicitly asks to limit the
+run — never as an automatic reaction to a not-ready module.
+
+## Step 2 — Branch check
+
+Before launching any subagent, verify the working branch:
+
+```bash
+cd "<projectPath>" && git branch --show-current
+```
+
+- If on `main` or `develop` → **do NOT halt**: record a `git.cannot-commit`
+  blocker (`userAction: run /gitflow start feature/develop-plan, then re-run`)
+  and proceed. Per-module commits get skipped (each `/ba-develop` handles that),
+  but the code still lands on disk.
+- If on a feature branch → proceed.
+
+## Step 3 — Wave-by-wave execution
+
+For each wave (in ascending order, starting from Wave 1):
+
+### 3a — Launch subagents (one per module, parallel within a wave)
+
+For each module in the wave, launch a **subagent** with the Agent tool:
+
+```
+Agent(
+  description: "ba-develop <APP>/<MODULE>",
+  prompt: "You are running /ba-develop for module <APP>/<MODULE>.
+    Module directory: .smartstack/ba/<APP>/<MODULE>
+    Project path: <projectPath>
+
+    Read the skill at skills/ba-develop/SKILL.md and follow its instructions
+    exactly. The module directory contains the PRD files (prd.md, prd.entities.md,
+    prd.api.md, prd.frontend.md, pagespecs/) and the upstream BA docs.
+
+    Execute all 4 phases (Core → Entities → API → Frontend) with gates.
+    Commit after each passed gate.
+
+    Return the output contract JSON when done.",
+)
+```
+
+**Parallelization rules:**
+- Modules in the **same wave** have no cross-module dependencies → they CAN
+  run in parallel (launch all subagents in one message).
+- Modules in **different waves** MUST be sequential (Wave N+1 depends on Wave N).
+- **Exception**: if two modules share the same application and Phase 0
+  (core-seed) writes to the same `CoreSeedData` file, you MUST serialize
+  Phase 0 across those modules. The simplest approach: run Phase 0 for ALL
+  modules in the wave first (serially if same app), then parallelize Phases 1–3.
+
+### 3b — Collect results
+
+After all subagents in the wave complete, collect their results.
+Each subagent returns (per `/ba-develop` output contract):
+
+```json
+{
+  "moduleDir": "...",
+  "moduleCode": "...",
+  "phases": [
+    { "name": "core", "status": "passed|passed-after-heal|completed-with-blockers|skipped", "commitHash": "..." },
+    ...
+  ],
+  "blockers": [ { "phase": "...", "kind": "...", "severity": "critical|high|medium", "summary": "...", "userAction": "..." } ],
+  "overallStatus": "success|success-after-heal|success-with-warnings|completed-with-blockers"
+}
+```
+
+`/ba-develop` never emits `failed` or `halted` — it always completes, returning
+`completed-with-blockers` whenever any item was deferred. Read `blockers[]`,
+not a failure status.
+
+### 3c — Wave checkpoint (never halts)
+
+`/ba-develop` always completes, so every module returns either a `success*` or
+`completed-with-blockers` status. The wave **never blocks the run**:
+
+1. **All modules `success*`** → record wave as `✅ passed`, proceed to next wave.
+2. **One or more modules `completed-with-blockers`** → record wave as
+   `⚠️ blockers`, **collect their `blockers[]` into the plan-level aggregate**,
+   and **proceed to the next wave anyway**. A deferred artifact in Wave N may
+   cause a Wave N+1 module to defer more items — that cascade is acceptable and
+   surfaces as additional blockers, never as a stop.
+3. Surface every collected blocker in the final report (§ Step 4).
+
+### 3d — Inter-wave compile check
+
+After the wave checkpoint, run a project-wide compile check:
+
+```bash
+cd "<projectPath>" && dotnet build --no-restore 2>&1
+```
+
+This catches cross-module integration issues (e.g. a module in Wave 2
+references a type from Wave 1 that was renamed). If the build fails, **do NOT
+halt** — record a `cross-wave.compile` blocker (high) with the error and
+proceed to the next wave. Later waves may be independent; any further breakage
+aggregates as more blockers.
+
+## Step 4 — Final report
+
+After all waves complete (the run always reaches this point — it never halts),
+emit a unified report:
+
+```
+## Development Plan Execution Report
+
+_Executed on <date> · <N> waves · <M> modules_
+
+### Wave Summary
+
+| Wave | Status | Modules | Duration |
+|------|--------|---------|----------|
+| 1    | ✅     | CRM/CONTACTS, BILLING/PRODUCTS | ~15min |
+| 2    | ✅     | CRM/PIPELINE | ~10min |
+| 3    | ⚠️     | BILLING/INVOICES (API deferred) | ~12min |
+
+### Per-Module Results
+
+| Module | Core | Entities | API | Frontend | Status |
+|--------|------|----------|-----|----------|--------|
+| CRM/CONTACTS | ✅ a1b2c3d | ✅ e4f5a6b | ✅ c7d8e9f | ✅ 01a2b3c | success |
+| BILLING/PRODUCTS | ✅ ... | ✅ ... | ✅ ... | ✅ ... | success |
+| CRM/PIPELINE | ✅ ... | ✅ ... | ✅ ... | ✅ ... | success-with-warnings |
+| BILLING/INVOICES | ✅ ... | ✅ ... | ⚠️ deferred | ✅ ... | completed-with-blockers |
+
+### Warnings
+- CRM/PIPELINE: 2 ACs not covered (UC-CRM-PIPELINE-OPPORTUNITES-001#AC-02, UC-CRM-PIPELINE-OPPORTUNITES-002#AC-01)
+
+### Blockers
+- BILLING/INVOICES (api.2a, high): business test count (3) < rule count (5) — deferred, run continued
+
+### Next Steps
+1. Address BILLING/INVOICES API blockers (add the missing rules/tests)
+2. Re-run: `/ba-develop-plan` (it will skip completed waves if commits exist)
+```
+
+## Re-run behavior
+
+When re-running after a partial run (interrupted, or one that finished with
+blockers the user has since addressed):
+
+1. The preflight CLI re-checks readiness (it may have changed).
+2. For each wave, check if all modules already have their commits:
+   - Use `git log --oneline --grep="feat(<moduleCode>):"` to detect existing commits.
+   - If ALL 4 phase commits exist for a module → **skip** it (already developed).
+   - If SOME commits exist → resume from the first phase without a commit (tell
+     the `/ba-develop` subagent which phase to start from).
+3. This avoids re-running already-completed work.
+
+## Anti-patterns
+
+- **Halting the run because a wave has blockers.** `/ba-develop` always
+  completes; a wave with `completed-with-blockers` modules proceeds to the next
+  wave. Cross-module FKs from Wave N+1 resolve to Wave N entities — if a Wave N
+  entity was deferred, Wave N+1 may defer more items; that cascade is acceptable
+  and aggregates as blockers. Surface the causal link in the report, never stop.
+- **Parallelizing across waves.** The topological sort guarantees the wave
+  order is safe. Violating it breaks FK resolution.
+- **Loading all modules' PRDs into your context.** You're the orchestrator —
+  you only need the plan structure. Each subagent loads only its own PRD.
+- **Modifying the plan during execution.** If you discover the plan is wrong,
+  defer it as a blocker (`userAction: re-run /ba-create-plan-development`) and
+  continue with the current plan — never halt.
+- **Ignoring the inter-wave compile gate.** Per-module gates catch intra-module
+  issues; the inter-wave gate catches cross-module integration issues.
+- **Running Phase 0 (core-seed) in parallel for modules of the same app.**
+  They write to the same `CoreSeedData.cs` — serialize Phase 0 within an app.
+
+## Non-goals
+
+- Does not replace `/ba-develop` — it orchestrates multiple calls to it.
+- Does not modify PRD files or BA tree.
+- Does not handle deployment or CI — execution is local only.
+- Does not invent a development order — it follows the plan from
+  `/ba-create-plan-development`.

package/templates/skills/ba-develop-plan/cli/preflight-develop-plan/__tests__/validate.test.ts

@@ -0,0 +1,225 @@
+/**
+ * validate.test.ts — Tests for preflight-develop-plan validation.
+ */
+import { describe, it, expect } from 'vitest';
+import { PreflightInputSchema } from '../types.js';
+import type { DevelopmentPlan, ReadinessInfo } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Zod input schema
+// ---------------------------------------------------------------------------
+
+describe('PreflightInputSchema', () => {
+  it('accepts valid input', () => {
+    const result = PreflightInputSchema.safeParse({
+      baRoot: '.smartstack/ba',
+      projectPath: '/path/to/project',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts input with specific waves', () => {
+    const result = PreflightInputSchema.safeParse({
+      baRoot: '.smartstack/ba',
+      projectPath: '/path/to/project',
+      waves: [1, 2],
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.waves).toEqual([1, 2]);
+    }
+  });
+
+  it('rejects empty baRoot', () => {
+    const result = PreflightInputSchema.safeParse({
+      baRoot: '',
+      projectPath: '/path/to/project',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects missing projectPath', () => {
+    const result = PreflightInputSchema.safeParse({
+      baRoot: '.smartstack/ba',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects wave 0 (external deps are not developable)', () => {
+    const result = PreflightInputSchema.safeParse({
+      baRoot: '.smartstack/ba',
+      projectPath: '/path/to/project',
+      waves: [0, 1],
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Readiness verdict patterns
+// ---------------------------------------------------------------------------
+
+describe('readiness verdict detection', () => {
+  const VERDICT_RE =
+    /Verdict\s*:\s*(GO|NO-GO)(?:.*?score\s+(\d+))?(?:.*?(\d+)\s+err)?(?:.*?(\d+)\s+warn)?/;
+
+  it('detects GO with high score', () => {
+    const line = '_2026-05-26 · Verdict : GO · score 92/100 · 0 err · 1 warn · 20 ok_';
+    const match = VERDICT_RE.exec(line);
+    expect(match).not.toBeNull();
+    expect(match![1]).toBe('GO');
+    expect(Number(match![2])).toBe(92);
+    expect(Number(match![3])).toBe(0);
+  });
+
+  it('detects NO-GO', () => {
+    const line = '_2026-05-26 · Verdict : NO-GO · score 65/100 · 5 err · 3 warn · 10 ok_';
+    const match = VERDICT_RE.exec(line);
+    expect(match).not.toBeNull();
+    expect(match![1]).toBe('NO-GO');
+    expect(Number(match![2])).toBe(65);
+    expect(Number(match![3])).toBe(5);
+  });
+
+  it('GO with score < 80 is detectable', () => {
+    const line = '_2026-05-26 · Verdict : GO · score 75/100 · 0 err · 8 warn_';
+    const match = VERDICT_RE.exec(line);
+    expect(match).not.toBeNull();
+    expect(match![1]).toBe('GO');
+    expect(Number(match![2])).toBe(75);
+    // Caller checks score < 80 → blocker
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Plan structure validation
+// ---------------------------------------------------------------------------
+
+describe('plan structure checks', () => {
+  function makePlan(overrides: Partial<DevelopmentPlan> = {}): DevelopmentPlan {
+    return {
+      generatedAt: '2026-05-26',
+      apps: ['CRM'],
+      totalModules: 2,
+      totalCrossModuleDeps: 1,
+      waves: [
+        {
+          level: 1,
+          modules: [
+            {
+              appCode: 'CRM',
+              moduleCode: 'CONTACTS',
+              key: 'CRM/CONTACTS',
+              entityCount: 3,
+              dependsOn: [],
+              readiness: { verdict: 'GO', score: 88, errCount: 0, warnCount: 2 },
+              isExternal: false,
+              warnings: [],
+            },
+          ],
+        },
+        {
+          level: 2,
+          modules: [
+            {
+              appCode: 'CRM',
+              moduleCode: 'PIPELINE',
+              key: 'CRM/PIPELINE',
+              entityCount: 4,
+              dependsOn: ['CRM/CONTACTS'],
+              readiness: { verdict: 'GO', score: 85, errCount: 0, warnCount: 1 },
+              isExternal: false,
+              warnings: [],
+            },
+          ],
+        },
+      ],
+      cycles: [],
+      warnings: [],
+      ...overrides,
+    };
+  }
+
+  it('valid plan has waves', () => {
+    const plan = makePlan();
+    expect(plan.waves.length).toBeGreaterThan(0);
+  });
+
+  it('empty waves should be rejected', () => {
+    const plan = makePlan({ waves: [] });
+    expect(plan.waves.length).toBe(0);
+  });
+
+  it('cycles are flagged', () => {
+    const plan = makePlan({
+      cycles: [['CRM/A', 'CRM/B']],
+    });
+    expect(plan.cycles.length).toBeGreaterThan(0);
+  });
+
+  it('external deps are in wave 0', () => {
+    const plan = makePlan({
+      waves: [
+        {
+          level: 0,
+          modules: [
+            {
+              appCode: 'HR',
+              moduleCode: 'EMPLOYEES',
+              key: 'HR/EMPLOYEES',
+              entityCount: 0,
+              dependsOn: [],
+              isExternal: true,
+              referencedBy: ['CRM/CONTACTS'],
+              warnings: [],
+            },
+          ],
+        },
+        ...makePlan().waves,
+      ],
+    });
+    const wave0 = plan.waves.find((w) => w.level === 0);
+    expect(wave0).toBeDefined();
+    expect(wave0!.modules[0].isExternal).toBe(true);
+  });
+
+  it('modules in the same wave have no mutual dependencies', () => {
+    const plan = makePlan({
+      waves: [
+        {
+          level: 1,
+          modules: [
+            {
+              appCode: 'CRM',
+              moduleCode: 'CONTACTS',
+              key: 'CRM/CONTACTS',
+              entityCount: 3,
+              dependsOn: [],
+              isExternal: false,
+              warnings: [],
+            },
+            {
+              appCode: 'BILLING',
+              moduleCode: 'PRODUCTS',
+              key: 'BILLING/PRODUCTS',
+              entityCount: 2,
+              dependsOn: [],
+              isExternal: false,
+              warnings: [],
+            },
+          ],
+        },
+      ],
+    });
+
+    const wave1 = plan.waves[0];
+    const wave1Keys = new Set(wave1.modules.map((m) => m.key));
+
+    // No module in wave 1 depends on another wave 1 module
+    for (const mod of wave1.modules) {
+      for (const dep of mod.dependsOn) {
+        expect(wave1Keys.has(dep)).toBe(false);
+      }
+    }
+  });
+});

package/templates/skills/ba-develop-plan/cli/preflight-develop-plan/index.ts

@@ -0,0 +1,102 @@
+/**
+ * preflight-develop-plan CLI — Entry point.
+ *
+ * Validates that the development plan (from /ba-create-plan-development) is executable:
+ * reads dev-plan.json, checks per-module PRD files and audit readiness, returns
+ * a PreflightReport as an ExecuteEnvelope.
+ *
+ * Usage:
+ *   npx tsx skills/ba-develop-plan/cli/preflight-develop-plan/index.ts \
+ *     --spec '{"baRoot": ".smartstack/ba", "projectPath": "/path/to/project"}'
+ */
+import { parseArgs } from 'node:util';
+import {
+  executeEnvelope,
+  failExecute,
+  printEnvelope,
+} from '../../../../lib/output.js';
+import { validateInput, checkReadiness } from './validate.js';
+import type { PreflightReport } from './types.js';
+
+const COMMAND = 'preflight-develop-plan';
+
+async function main(): Promise<void> {
+  // --- 1. Parse CLI arguments ---
+  const { values } = parseArgs({
+    options: {
+      spec: { type: 'string' },
+    },
+    strict: false,
+  });
+
+  if (!values.spec) {
+    printEnvelope(failExecute(COMMAND, ['Missing required --spec argument']));
+    process.exit(1);
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(values.spec);
+  } catch {
+    printEnvelope(failExecute(COMMAND, ['Invalid JSON in --spec argument']));
+    process.exit(1);
+  }
+
+  // --- 2. Validate input + read plan ---
+  const validation = await validateInput(raw);
+  if (!validation.valid || !validation.spec || !validation.plan) {
+    printEnvelope(failExecute(COMMAND, validation.errors));
+    process.exit(1);
+  }
+
+  // --- 3. Check per-module readiness ---
+  const report = await checkReadiness(validation.spec, validation.plan);
+
+  // --- 4. Print report ---
+  const allWarnings = [...validation.warnings];
+  for (const wave of report.waves) {
+    for (const mod of wave.modules) {
+      allWarnings.push(...mod.warnings);
+    }
+  }
+
+  const errors: string[] = [];
+  if (!report.canProceed) {
+    errors.push('No waves are ready for development — fix blockers first');
+  }
+
+  const nextSteps: string[] = [];
+  if (report.canProceed) {
+    nextSteps.push(
+      `Ready to develop waves ${report.firstReadyWave}${report.lastReadyWave !== report.firstReadyWave ? `–${report.lastReadyWave}` : ''} (${report.readyModules} modules)`,
+    );
+  }
+
+  // Blocked modules
+  for (const wave of report.waves) {
+    for (const mod of wave.modules) {
+      if (mod.status === 'not-ready') {
+        nextSteps.push(`Fix ${mod.key}: ${mod.blockers.join('; ')}`);
+      }
+    }
+  }
+
+  printEnvelope(
+    executeEnvelope<PreflightReport>(COMMAND, {
+      success: report.canProceed,
+      report,
+      errors,
+      warnings: allWarnings,
+      nextSteps,
+    }),
+  );
+
+  if (!report.canProceed) process.exit(1);
+}
+
+main().catch((err) => {
+  printEnvelope(
+    failExecute(COMMAND, [err instanceof Error ? err.message : String(err)]),
+  );
+  process.exit(1);
+});

package/templates/skills/ba-develop-plan/cli/preflight-develop-plan/types.ts

@@ -0,0 +1,121 @@
+/**
+ * types.ts — Zod input schema + internal interfaces for preflight-develop-plan CLI.
+ *
+ * Validates that the development plan is executable: all modules have PRD files,
+ * audit verdicts, and are dev-ready (GO, score ≥ 80).
+ */
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Input schema (Zod)
+// ---------------------------------------------------------------------------
+
+export const PreflightInputSchema = z.object({
+  /** Absolute path to the .smartstack/ba/ directory. */
+  baRoot: z.string().min(1),
+
+  /** Absolute path to the target project (where generated code lands). */
+  projectPath: z.string().min(1),
+
+  /**
+   * Optional: only preflight specific waves.
+   * If omitted, all waves are checked.
+   */
+  waves: z.array(z.number().int().min(1)).optional(),
+});
+
+export type PreflightInput = z.infer<typeof PreflightInputSchema>;
+
+// ---------------------------------------------------------------------------
+// Plan structures (read from dev-plan.json — matches create-plan-development types)
+// ---------------------------------------------------------------------------
+
+export interface ReadinessInfo {
+  verdict: 'GO' | 'NO-GO' | 'UNKNOWN';
+  score?: number;
+  errCount?: number;
+  warnCount?: number;
+}
+
+export interface WaveModule {
+  appCode: string;
+  moduleCode: string;
+  key: string; // APP/MODULE
+  entityCount: number;
+  dependsOn: string[];
+  readiness?: ReadinessInfo;
+  isExternal: boolean;
+  referencedBy?: string[];
+  warnings: string[];
+}
+
+export interface Wave {
+  level: number;
+  modules: WaveModule[];
+}
+
+export interface DevelopmentPlan {
+  generatedAt: string;
+  apps: string[];
+  totalModules: number;
+  totalCrossModuleDeps: number;
+  waves: Wave[];
+  cycles: string[][];
+  warnings: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Preflight result
+// ---------------------------------------------------------------------------
+
+export type ModuleStatus = 'ready' | 'not-ready' | 'external';
+
+export interface ModulePreflight {
+  appCode: string;
+  moduleCode: string;
+  key: string;
+  wave: number;
+  status: ModuleStatus;
+  /** Directory: .smartstack/ba/<APP>/<MODULE> */
+  moduleDir: string;
+  /** PRD dev-readiness */
+  readiness: ReadinessInfo;
+  /** Which PRD files are present */
+  prdFiles: {
+    prd: boolean;
+    entities: boolean;
+    api: boolean;
+    frontend: boolean;
+    pagespecs: boolean;
+  };
+  /** Blocking issues for this module */
+  blockers: string[];
+  /** Non-blocking issues */
+  warnings: string[];
+}
+
+export interface WavePreflight {
+  level: number;
+  status: 'ready' | 'blocked';
+  modules: ModulePreflight[];
+  /** Modules in this wave that block execution */
+  blockers: string[];
+}
+
+export interface PreflightReport {
+  planDate: string;
+  apps: string[];
+  projectPath: string;
+  totalModules: number;
+  readyModules: number;
+  blockedModules: number;
+  externalDeps: number;
+  hasCycles: boolean;
+  waves: WavePreflight[];
+  /** Overall: can we proceed? */
+  canProceed: boolean;
+  /** First wave that is fully ready (all modules ready) */
+  firstReadyWave: number | null;
+  /** Last wave that is fully ready */
+  lastReadyWave: number | null;
+}