create-byan-agent 2.19.1 → 2.20.0

package/install/templates/.claude/workflows/document-project.js

@@ -0,0 +1,455 @@
+export const meta = {
+  name: 'document-project',
+  description: 'Faithful native port of the BYAN document-project full-scan pipeline: scan a brownfield codebase and emit comprehensive reference docs (overview, tech stack, source tree, conditional analysis, per-part architecture, master index) for AI-assisted development. Mirrors full-scan-instructions.md steps 1-12. Human gates (scan-level choice, classification confirmation, review iteration) stay OUT of the script and surface as a verdict.',
+  phases: [
+    { title: 'CLASSIFY' },
+    { title: 'EXISTING_DOCS' },
+    { title: 'TECH_STACK' },
+    { title: 'CONDITIONAL_ANALYSIS' },
+    { title: 'SOURCE_TREE' },
+    { title: 'DEV_OPS' },
+    { title: 'INTEGRATION' },
+    { title: 'ARCHITECTURE' },
+    { title: 'SUPPORTING_DOCS' },
+    { title: 'MASTER_INDEX' },
+    { title: 'VALIDATE' },
+    { title: 'FINALIZE' }
+  ]
+}
+
+// FD/STRICT CONTRACT (re-asserted): this script returns data only. It NEVER imports
+// or writes lib/fd-state.js / fd-state.json, and records no platform/strict state.
+// The orchestrating skill records FD/strict state via MCP at the human gate. The
+// script also uses no wall-clock and no randomness (both break Workflow resume);
+// any timestamp/id is passed in via args. The byan-lint-workflows linter forbids
+// fd-state coupling here.
+
+// Inputs (passed by the orchestrating skill; no fs / no clock / no RNG here).
+const projectRoot = (args && args.projectRoot) || process.cwd()
+const outputFolder = (args && args.outputFolder) || '_byan-output/project-documentation'
+// scan_level mirrors the source human gate (quick | deep | exhaustive). The script
+// does NOT prompt for it; it threads the choice through. Default = quick (source default).
+const scanLevel = (args && args.scanLevel) || 'quick'
+// workflow_mode mirrors the source router: initial_scan | full_rescan. deep_dive is a
+// separate sub-workflow and is intentionally out of this full-scan port's scope.
+const workflowMode = (args && args.workflowMode) || 'initial_scan'
+const runDate = (args && args.date) || 'unspecified'
+
+const reqCsv = projectRoot + '/_byan/workflow/simple/document-project/documentation-requirements.csv'
+
+log('document-project full-scan port — mode=' + workflowMode + ' scan_level=' + scanLevel)
+log('project_root=' + projectRoot + ' output=' + outputFolder)
+
+// STEP 1 — Detect project structure and classify project type.
+phase('CLASSIFY')
+const classification = await agent(
+  'You are documenting the brownfield project rooted at "' + projectRoot + '". ' +
+  'STEP 1 (document-project full-scan): detect repository structure and classify project type(s). ' +
+  'Scan the root for directory markers (client/ server/ api/ src/ app/ packages/) and key manifest files ' +
+  '(package.json, go.mod, requirements.txt, Cargo.toml, pom.xml, etc.). ' +
+  'Decide repository_type: monolith | monorepo | multi-part. For each distinct part, identify its root path and ' +
+  'match detected tech/file patterns against key_file_patterns in the documentation-requirements CSV at "' + reqCsv + '" ' +
+  '(12 project types: web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded, and a fallback). ' +
+  'Assign a project_type_id and display_name to each part. ' +
+  'Do NOT confirm with the user — record the classification so the orchestrating skill can confirm it at the human gate.',
+  {
+    label: 'classify-project',
+    phase: 'CLASSIFY',
+    schema: {
+      type: 'object',
+      required: ['repositoryType', 'parts'],
+      properties: {
+        repositoryType: { type: 'string', enum: ['monolith', 'monorepo', 'multi-part'] },
+        primaryLanguage: { type: 'string' },
+        parts: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['partId', 'rootPath', 'projectTypeId'],
+            properties: {
+              partId: { type: 'string' },
+              rootPath: { type: 'string' },
+              projectTypeId: { type: 'string' },
+              displayName: { type: 'string' }
+            }
+          }
+        },
+        classificationSummary: { type: 'string' }
+      }
+    }
+  }
+)
+
+const parts = (classification && classification.parts) || []
+const isMultiPart = classification.repositoryType !== 'monolith' && parts.length > 1
+log('classified as ' + classification.repositoryType + ' with ' + parts.length + ' part(s)')
+
+// STEP 2 — Discover existing documentation and gather user context.
+phase('EXISTING_DOCS')
+const existingDocs = await agent(
+  'STEP 2 (document-project): for each part of this ' + classification.repositoryType + ' project, ' +
+  'inventory existing documentation. Scan for README.*, CONTRIBUTING.*, ARCHITECTURE.*, DEPLOYMENT.*/DEPLOY.*, ' +
+  'API.*, and anything under docs/, documentation/, .github/. ' +
+  'For each doc record: file path, doc type (readme | architecture | api | deployment | contributing | other), ' +
+  'and the owning part id when multi-part. ' +
+  'Do NOT ask the user for extra focus areas — that is a human gate; just return the inventory.',
+  {
+    label: 'existing-docs',
+    phase: 'EXISTING_DOCS',
+    schema: {
+      type: 'object',
+      required: ['docs'],
+      properties: {
+        docs: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['path', 'docType'],
+            properties: {
+              path: { type: 'string' },
+              docType: { type: 'string' },
+              partId: { type: 'string' }
+            }
+          }
+        },
+        count: { type: 'number' }
+      }
+    }
+  }
+)
+log('found ' + ((existingDocs && existingDocs.docs && existingDocs.docs.length) || 0) + ' existing doc(s)')
+
+// STEP 3 — Analyze technology stack for each part.
+phase('TECH_STACK')
+const techStack = await agent(
+  'STEP 3 (document-project): analyze the technology stack for each part. ' +
+  'Parse manifest files (package.json, go.mod, requirements.txt, Cargo.toml, etc.) per part to extract ' +
+  'framework, language, version, database, and key dependencies. Build a technology table ' +
+  '(Category, Technology, Version, Justification). Determine the architecture pattern per part, driven by its ' +
+  'project_type_id and framework (e.g. web -> layered/component-based, backend -> service/API-centric, ' +
+  'React -> component hierarchy, Express -> middleware pipeline). ' +
+  'Parts to cover: ' + JSON.stringify(parts.map(p => p.partId)) + '.',
+  {
+    label: 'tech-stack',
+    phase: 'TECH_STACK',
+    schema: {
+      type: 'object',
+      required: ['perPart'],
+      properties: {
+        perPart: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['partId', 'framework', 'language'],
+            properties: {
+              partId: { type: 'string' },
+              framework: { type: 'string' },
+              language: { type: 'string' },
+              database: { type: 'string' },
+              architecturePattern: { type: 'string' },
+              dependencies: { type: 'array', items: { type: 'string' } }
+            }
+          }
+        }
+      }
+    }
+  }
+)
+
+// STEP 4 — Conditional analysis driven by documentation_requirements boolean flags.
+// scan_level gates depth: quick = pattern/glob only (no source reading); deep = read
+// critical_directories; exhaustive = read all source (excl node_modules/.git/dist/build/coverage).
+phase('CONDITIONAL_ANALYSIS')
+const conditional = await agent(
+  'STEP 4 (document-project): perform conditional analysis per part, honoring scan_level="' + scanLevel + '". ' +
+  'For scan_level=quick use glob/grep and config/filename patterns ONLY — do NOT open source files. ' +
+  'For scan_level=deep read files in the critical_directories for each part type. ' +
+  'For scan_level=exhaustive read all source files (exclude node_modules, .git, dist, build, coverage), ' +
+  'processing one subfolder at a time. ' +
+  'For each part, consult its documentation_requirements row (from "' + reqCsv + '") and run the scans whose flag is true: ' +
+  'requires_api_scan -> catalog API routes/endpoints (controllers/ routes/ api/ handlers/), write api-contracts-{part}.md; ' +
+  'requires_data_models -> catalog schemas/entities/migrations (models/ schemas/ prisma/), write data-models-{part}.md; ' +
+  'requires_state_management -> identify stores/reducers/actions; ' +
+  'requires_ui_components -> inventory components/ ui/ widgets/ views/; ' +
+  'requires_hardware_docs -> note hardware/pinout/schematic references; ' +
+  'requires_asset_inventory -> catalog images/audio/models/sprites/textures. ' +
+  'Also scan supplementary patterns: config, auth/security, entry points, shared code, async/events, ci/cd, localization. ' +
+  'Return counts and the artifact filenames you would write.',
+  {
+    label: 'conditional-analysis',
+    phase: 'CONDITIONAL_ANALYSIS',
+    schema: {
+      type: 'object',
+      required: ['perPart'],
+      properties: {
+        perPart: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['partId'],
+            properties: {
+              partId: { type: 'string' },
+              apiEndpointCount: { type: 'number' },
+              dataModelCount: { type: 'number' },
+              uiComponentCount: { type: 'number' },
+              hasStateManagement: { type: 'boolean' },
+              hasAssets: { type: 'boolean' },
+              filesGenerated: { type: 'array', items: { type: 'string' } }
+            }
+          }
+        }
+      }
+    }
+  }
+)
+
+// STEP 5 — Source tree analysis with annotations.
+phase('SOURCE_TREE')
+const sourceTree = await agent(
+  'STEP 5 (document-project): generate an annotated source tree per part using each part\'s critical_directories. ' +
+  'Annotate the purpose of each critical directory, mark entry points, highlight key file locations, and ' +
+  '(for multi-part projects) note integration/interface points between parts. ' +
+  'Produce the content for source-tree-analysis.md.',
+  {
+    label: 'source-tree',
+    phase: 'SOURCE_TREE',
+    schema: {
+      type: 'object',
+      required: ['outputFile'],
+      properties: {
+        outputFile: { type: 'string' },
+        criticalFolderCount: { type: 'number' },
+        treeMarkdown: { type: 'string' }
+      }
+    }
+  }
+)
+
+// STEP 6 — Extract development and operational information.
+phase('DEV_OPS')
+const devOps = await agent(
+  'STEP 6 (document-project): extract development and operational info. ' +
+  'From manifests, configs, and existing docs determine: prerequisites (runtime versions), install steps, ' +
+  'environment setup (.env/config), build commands, run commands, and test commands (using test_file_patterns). ' +
+  'Detect deployment config via ci/cd patterns: Dockerfile, docker-compose.yml, k8s/, helm/, .github/workflows/, ' +
+  '.gitlab-ci.yml, deployment scripts, terraform/, pulumi/. ' +
+  'If a CONTRIBUTING file exists, extract code style, PR process, commit conventions, testing requirements. ' +
+  'Report which of dev-setup / deployment / contribution were found.',
+  {
+    label: 'dev-ops',
+    phase: 'DEV_OPS',
+    schema: {
+      type: 'object',
+      required: ['devSetupDocumented'],
+      properties: {
+        devSetupDocumented: { type: 'boolean' },
+        deploymentFound: { type: 'boolean' },
+        contributionFound: { type: 'boolean' },
+        notes: { type: 'string' }
+      }
+    }
+  }
+)
+
+// STEP 7 — Multi-part integration architecture (only when project has multiple parts).
+phase('INTEGRATION')
+let integration = { applicable: false, integrationPoints: [] }
+if (isMultiPart) {
+  integration = await agent(
+    'STEP 7 (document-project): this is a multi-part project. Analyze how parts communicate ' +
+    '(REST, GraphQL, gRPC, message queues, shared databases) via integration_scan_patterns. ' +
+    'Build an integration_points list of { from, to, type, details } and produce integration-architecture.md content.',
+    {
+      label: 'integration-architecture',
+      phase: 'INTEGRATION',
+      schema: {
+        type: 'object',
+        required: ['integrationPoints'],
+        properties: {
+          integrationPoints: {
+            type: 'array',
+            items: {
+              type: 'object',
+              required: ['from', 'to', 'type'],
+              properties: {
+                from: { type: 'string' },
+                to: { type: 'string' },
+                type: { type: 'string' },
+                details: { type: 'string' }
+              }
+            }
+          },
+          outputFile: { type: 'string' }
+        }
+      }
+    }
+  )
+  integration.applicable = true
+} else {
+  log('single-part project — integration architecture step skipped (mirrors source if-guard)')
+}
+
+// STEP 8 — Generate architecture documentation for each part.
+phase('ARCHITECTURE')
+const architecture = await agent(
+  'STEP 8 (document-project): generate architecture documentation per part. For each part fill: ' +
+  'Executive Summary, Technology Stack (Step 3), Architecture Pattern, Data Architecture (Step 4 data models), ' +
+  'API Design (Step 4 APIs if applicable), Component Overview (Step 4 components if applicable), Source Tree (Step 5), ' +
+  'Development Workflow + Deployment Architecture (Step 6), Testing Strategy. ' +
+  'For a single-part project write architecture.md; for multi-part write architecture-{part}.md per part. ' +
+  'No placeholder sections — every section must be filled from discovered data. Report the files you would write.',
+  {
+    label: 'architecture-docs',
+    phase: 'ARCHITECTURE',
+    schema: {
+      type: 'object',
+      required: ['files'],
+      properties: {
+        files: { type: 'array', items: { type: 'string' } }
+      }
+    }
+  }
+)
+
+// STEP 9 — Generate supporting documentation files.
+phase('SUPPORTING_DOCS')
+const supporting = await agent(
+  'STEP 9 (document-project): generate the supporting docs from the discovered data. Always: ' +
+  'project-overview.md (name, purpose, exec summary, tech stack table, architecture type, repo structure, links) ' +
+  'and source-tree-analysis.md. Conditionally: component-inventory(-{part}).md if UI components exist; ' +
+  'development-guide(-{part}).md; deployment-guide.md if deployment config found; contribution-guide.md if guidelines found; ' +
+  'api-contracts(-{part}).md if APIs documented; data-models(-{part}).md if data models found; ' +
+  'and for multi-part: integration-architecture.md + project-parts.json metadata. ' +
+  'Use the (To be generated) marker exactly for any doc that should exist but cannot be produced. ' +
+  'Return the full list of files written.',
+  {
+    label: 'supporting-docs',
+    phase: 'SUPPORTING_DOCS',
+    schema: {
+      type: 'object',
+      required: ['files'],
+      properties: {
+        files: { type: 'array', items: { type: 'string' } },
+        toBeGeneratedMarkers: { type: 'array', items: { type: 'string' } }
+      }
+    }
+  }
+)
+
+// STEP 10 — Generate master index as the primary AI retrieval source.
+phase('MASTER_INDEX')
+const masterIndex = await agent(
+  'STEP 10 (document-project): write index.md — the master entry point for AI-assisted development. ' +
+  'Include: Project Overview (type/repository_type, primary language, architecture), Quick Reference ' +
+  '(single-part: tech stack/entry point/pattern; multi-part: per-part block), Generated Documentation links, ' +
+  'Existing Documentation links, and a Getting Started section. ' +
+  'Before linking each generated doc, check whether the file actually exists; if a doc was expected but missing, ' +
+  'append the EXACT marker "(To be generated)" to its link so Step 11 can detect it. ' +
+  'Return the missing-doc list captured from those markers.',
+  {
+    label: 'master-index',
+    phase: 'MASTER_INDEX',
+    schema: {
+      type: 'object',
+      required: ['outputFile'],
+      properties: {
+        outputFile: { type: 'string' },
+        missingDocs: { type: 'array', items: { type: 'string' } }
+      }
+    }
+  }
+)
+
+// STEP 11 — Validate against checklist + detect incomplete-documentation markers.
+// The source loops here at a HUMAN gate (generate-incomplete / review / finalize). The
+// script does NOT loop or prompt: it runs the validation + marker scan once and returns a
+// verdict; the orchestrating skill drives the iteration at the gate.
+phase('VALIDATE')
+const validation = await agent(
+  'STEP 11 (document-project): validate the generated documentation set against the checklist ' +
+  '(checklist.md): write-as-you-go coverage, classification accuracy, tech-stack completeness, file completeness, ' +
+  'index navigation, brownfield-PRD readiness. ' +
+  'Then scan index.md for incomplete-documentation markers: PRIMARY exact "(To be generated)", FALLBACK fuzzy ' +
+  '"(TBD)" "(TODO)" "(Coming soon)" "(Not yet generated)" "(Pending)". ' +
+  'For each marker capture { title, filePath, docType, partId, fuzzyMatch }. ' +
+  'Do NOT prompt the user to generate/review/finalize — return a verdict the orchestrating skill presents at the gate.',
+  {
+    label: 'validate-docs',
+    phase: 'VALIDATE',
+    schema: {
+      type: 'object',
+      required: ['checklistPassed', 'incompleteDocs'],
+      properties: {
+        checklistPassed: { type: 'boolean' },
+        criticalIssues: { type: 'array', items: { type: 'string' } },
+        incompleteDocs: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['title', 'docType'],
+            properties: {
+              title: { type: 'string' },
+              filePath: { type: 'string' },
+              docType: { type: 'string' },
+              partId: { type: 'string' },
+              fuzzyMatch: { type: 'boolean' }
+            }
+          }
+        }
+      }
+    }
+  }
+)
+
+// STEP 12 — Finalize and compile the summary report.
+phase('FINALIZE')
+const finalize = await agent(
+  'STEP 12 (document-project): compile the final summary. List every generated file under "' + outputFolder + '" ' +
+  'with the master index (index.md) flagged as the primary entry point. Compile the verification recap: ' +
+  'verificationSummary (concrete tests/extractions executed, or "none run"), openRisks (remaining risks/TODOs, or "none"), ' +
+  'nextChecks (recommended actions before a brownfield PRD / PR, or "none"). ' +
+  'Run date provided by orchestrator: ' + runDate + '.',
+  {
+    label: 'finalize',
+    phase: 'FINALIZE',
+    schema: {
+      type: 'object',
+      required: ['generatedFiles'],
+      properties: {
+        generatedFiles: { type: 'array', items: { type: 'string' } },
+        verificationSummary: { type: 'string' },
+        openRisks: { type: 'string' },
+        nextChecks: { type: 'string' }
+      }
+    }
+  }
+)
+
+const incompleteCount = (validation && validation.incompleteDocs && validation.incompleteDocs.length) || 0
+
+// The human decision (review-iteration loop / finalize) lives OUTSIDE the script.
+// We return a structured verdict; needsHumanGate is true so the orchestrating skill can
+// present classification confirmation + the incomplete-docs menu and record FD/strict state.
+return {
+  workflow: 'document-project',
+  summary: 'Documented ' + classification.repositoryType + ' project (' + parts.length +
+    ' part(s)) at scan_level=' + scanLevel + '; ' + incompleteCount + ' incomplete-doc marker(s) detected.',
+  steps: 12,
+  mode: workflowMode,
+  scanLevel: scanLevel,
+  needsHumanGate: true,
+  classification: classification,
+  result: {
+    existingDocs: existingDocs,
+    techStack: techStack,
+    conditionalAnalysis: conditional,
+    sourceTree: sourceTree,
+    devOps: devOps,
+    integration: integration,
+    architecture: architecture,
+    supportingDocs: supporting,
+    masterIndex: masterIndex,
+    validation: validation,
+    finalize: finalize
+  }
+}

package/install/templates/.claude/workflows/qa-automate.js

@@ -0,0 +1,169 @@
+export const meta = {
+  name: 'qa-automate',
+  description: 'Native port of the BYAN qa-automate (Quinn QA) workflow: autonomously generate automated API + E2E tests for already-implemented code using the project\'s existing test framework, run them to green (bounded fix loop), and return a structured test-automation summary for the orchestrating skill to present at the human gate.',
+  phases: [
+    { title: 'DETECT', detail: 'Step 0 - detect the project test framework' },
+    { title: 'IDENTIFY', detail: 'Step 1 - identify the features/dirs to test' },
+    { title: 'API_TESTS', detail: 'Step 2 - generate API tests (if applicable)' },
+    { title: 'E2E_TESTS', detail: 'Step 3 - generate E2E tests (if UI exists)' },
+    { title: 'RUN', detail: 'Step 4 - run tests, fix failures immediately (bounded loop)' },
+    { title: 'SUMMARY', detail: 'Step 5 - produce the test-automation summary verdict' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// FD / STRICT STATE CONTRACT  (re-asserted inline — enforcement-bridge).
+//
+// The in-CLI Workflow tool runs this script OUTSIDE the conversation turn, so
+// BYAN's main-thread hooks (fd-phase-guard, strict-scope-guard, strict-stop-
+// guard, mantra-validate) DO NOT fire here. This script therefore:
+//   - NEVER imports/requires _byan/.../lib/fd-state.js and NEVER writes
+//     fd-state.json directly  (enforced by byan-lint-workflows.js).
+//   - uses NO wall-clock and NO randomness primitive (Date/RNG break
+//     resume); any date/id must arrive via args.
+//   - returns DATA only. The orchestrating skill is the human-gated conductor;
+//     IT records FD/strict state via the byan_fd_* / byan_strict_* MCP tools
+//     AT the gate. The generated test FILES + the summary markdown are the
+//     workflow's product, not BYAN platform state.
+// ---------------------------------------------------------------------------
+
+// Convergence guard for Step 4 ("Run Tests ... If failures occur, fix them
+// immediately"). The source prose has no explicit cap, but an autonomous fix
+// loop must be bounded so the model cannot spin forever in the sandbox. Hard
+// cap = 3 fix attempts; turns the prose into a real JS counter.
+const MAX_FIX_ATTEMPTS = 3
+
+const RUN_SCHEMA = {
+  type: 'object',
+  required: ['pass', 'fixed'],
+  properties: {
+    pass: { type: 'boolean', description: 'true ONLY if the full generated test suite passes via the project test command' },
+    fixed: { type: 'boolean', description: 'true if this attempt changed test/source code to address failures' },
+    failures: { type: 'array', items: { type: 'string' }, description: 'precise failing tests / errors when not passing' },
+    testCommand: { type: 'string', description: 'the exact command used to run the tests' },
+    summary: { type: 'string', description: 'one-line run status' },
+  },
+}
+
+const SUMMARY_SCHEMA = {
+  type: 'object',
+  required: ['ok', 'apiTestFiles', 'e2eTestFiles', 'allPass'],
+  properties: {
+    ok: { type: 'boolean', description: 'true if a complete, faithful test-automation summary was produced' },
+    apiTestFiles: { type: 'array', items: { type: 'string' }, description: 'relative paths of generated API test files' },
+    e2eTestFiles: { type: 'array', items: { type: 'string' }, description: 'relative paths of generated E2E test files' },
+    allPass: { type: 'boolean', description: 'true if all generated tests pass' },
+    apiCoverage: { type: 'string', description: 'e.g. "5/10 endpoints covered"' },
+    uiCoverage: { type: 'string', description: 'e.g. "3/8 UI features covered"' },
+    summaryPath: { type: 'string', description: 'path the test-summary.md was written to (implementation_artifacts/tests/test-summary.md)' },
+    notes: { type: 'string', description: 'next steps / caveats' },
+  },
+}
+
+// Inputs arrive via args (no clock/RNG inside the script).
+const target = (args && args.target) || 'auto-discover features in the codebase'
+const testDir = (args && args.testDir) || '{project-root}/tests'
+const sourceDir = (args && args.sourceDir) || '{project-root}'
+const summaryPath = (args && args.summaryPath) || '{implementation_artifacts}/tests/test-summary.md'
+
+// --- Step 0: Detect Test Framework -----------------------------------------
+phase('DETECT')
+const framework = await agent(
+  `You are Quinn (BYAN QA), running qa-automate Step 0 (Detect Test Framework). ` +
+    `Scope: GENERATE TESTS ONLY — do NOT do code review or story validation. ` +
+    `Inspect the project under ${JSON.stringify(sourceDir)}: read package.json dependencies for an existing test ` +
+    `framework (playwright, jest, vitest, cypress, etc.) and read existing test files to learn the project's patterns. ` +
+    `Use whatever framework the project already has. If NO framework exists: analyze the source to determine the project ` +
+    `type (React, Vue, Node API, ...), determine the currently recommended test framework for that stack, and propose it ` +
+    `(flag that user confirmation is normally required). Report: detected framework, version, config file, conventions, ` +
+    `and the test command. State explicitly if none was found.`,
+  { label: 'detect-framework', phase: 'DETECT' }
+)
+
+// --- Step 1: Identify Features ----------------------------------------------
+phase('IDENTIFY')
+const features = await agent(
+  `qa-automate Step 1 (Identify Features). Target requested: ${JSON.stringify(target)}. ` +
+    `Framework context: ${framework}\n` +
+    `Determine exactly what to test: a specific feature/component, a directory to scan (e.g. src/components/), ` +
+    `or auto-discover features across ${JSON.stringify(sourceDir)}. Classify each into API surfaces (endpoints/services) ` +
+    `vs UI surfaces (components/pages with user interaction). Report the concrete list of testable units with their files.`,
+  { label: 'identify-features', phase: 'IDENTIFY' }
+)
+
+// --- Step 2: Generate API Tests (if applicable) -----------------------------
+phase('API_TESTS')
+const apiTests = await agent(
+  `qa-automate Step 2 (Generate API Tests, if applicable). Framework: ${framework}\nFeatures: ${features}\n` +
+    `For each API endpoint/service identified, generate tests using the project's existing framework patterns that: ` +
+    `test status codes (200/400/404/500), validate response structure, and cover the happy path + 1-2 error cases. ` +
+    `Write them under ${JSON.stringify(testDir)} (e.g. tests/api/...). Keep them simple — standard framework APIs, no ` +
+    `complex fixture composition, no over-engineering. If there are no API surfaces, skip and say so. ` +
+    `Report the generated API test file paths.`,
+  { label: 'generate-api-tests', phase: 'API_TESTS' }
+)
+
+// --- Step 3: Generate E2E Tests (if UI exists) ------------------------------
+phase('E2E_TESTS')
+const e2eTests = await agent(
+  `qa-automate Step 3 (Generate E2E Tests, if UI exists). Framework: ${framework}\nFeatures: ${features}\n` +
+    `For each UI feature identified, generate end-to-end tests that: cover user workflows end-to-end, use semantic ` +
+    `locators (roles, labels, text — not brittle CSS), focus on real user interactions (clicks, form fills, navigation), ` +
+    `assert visible outcomes, and stay linear and simple. Follow the project's existing test patterns. ` +
+    `Forbid hardcoded waits/sleeps; tests must be independent (no order dependency). Write them under ` +
+    `${JSON.stringify(testDir)} (e.g. tests/e2e/...). If there is no UI, skip and say so. Report the generated E2E test file paths.`,
+  { label: 'generate-e2e-tests', phase: 'E2E_TESTS' }
+)
+
+// --- Step 4: Run Tests (with immediate-fix, bounded loop) -------------------
+phase('RUN')
+// "Execute tests to verify they pass. If failures occur, fix them immediately."
+// Bounded so an autonomous fix loop cannot spin forever.
+let attempts = 0
+let run = { pass: false, fixed: false, failures: ['not started'] }
+while (true) {
+  attempts += 1
+  run = await agent(
+    `qa-automate Step 4 (Run Tests), attempt ${attempts}/${MAX_FIX_ATTEMPTS}. Framework: ${framework}\n` +
+      `Generated API tests: ${apiTests}\nGenerated E2E tests: ${e2eTests}\n` +
+      `Run the generated tests using the project's test command. Set pass=true ONLY if the full generated suite passes. ` +
+      `If failures occur, FIX them immediately (correct the tests or the obviously-broken test setup — do NOT silently ` +
+      `delete tests to make them pass) and report fixed=true with the precise failures addressed. ` +
+      `Report the exact test command used.`,
+    { label: `run-tests-attempt-${attempts}`, phase: 'RUN', schema: RUN_SCHEMA }
+  )
+  log(`run attempt ${attempts}: pass=${Boolean(run && run.pass)} fixed=${Boolean(run && run.fixed)}`)
+  if (run && run.pass) break
+  if (attempts >= MAX_FIX_ATTEMPTS) break
+}
+
+// --- Step 5: Create Summary -------------------------------------------------
+phase('SUMMARY')
+const summary = await agent(
+  `qa-automate Step 5 (Create Summary). Produce the Test Automation Summary markdown and save it to ` +
+    `${JSON.stringify(summaryPath)}. Use the source template sections: Generated Tests (API Tests, E2E Tests with ` +
+    `checkboxes + one-line description per file), Coverage (API endpoints X/Y, UI features X/Y), and Next Steps.\n` +
+    `Inputs — API tests: ${apiTests}\nE2E tests: ${e2eTests}\nRun result: ${JSON.stringify(run)}\n` +
+    `Be faithful: list only files actually generated; do not over-state coverage. Return the structured fields.`,
+  { label: 'create-summary', phase: 'SUMMARY', schema: SUMMARY_SCHEMA }
+)
+
+// Return DATA only. The orchestrating skill presents this at the human gate
+// and records FD/strict state via MCP.
+return {
+  workflow: 'qa-automate',
+  target,
+  framework,
+  steps: 6,
+  apiTestFiles: (summary && summary.apiTestFiles) || [],
+  e2eTestFiles: (summary && summary.e2eTestFiles) || [],
+  allTestsPass: Boolean(run && run.pass),
+  fixAttempts: attempts,
+  maxFixAttempts: MAX_FIX_ATTEMPTS,
+  failures: (run && run.failures) || [],
+  apiCoverage: (summary && summary.apiCoverage) || 'unknown',
+  uiCoverage: (summary && summary.uiCoverage) || 'unknown',
+  summaryPath: (summary && summary.summaryPath) || summaryPath,
+  notes: (summary && summary.notes) || '',
+  needsHumanGate: true,
+}