agentweaver 0.1.2 → 0.1.4

package/README.md

@@ -11,26 +11,30 @@ The package is designed to run as an npm CLI and includes an interactive termina
 ## What It Does
 
 - Fetches a Jira issue by key or browse URL
-- Generates workflow artifacts such as design, implementation plan, QA plan, reviews, and summaries
-- Runs workflow stages like `plan`, `implement`, `review`, `review-fix`, `test`, and `auto`
-- Persists `auto` pipeline state on disk so runs can resume
+- Generates workflow artifacts such as design, implementation plan, QA plan, bug analysis, reviews, and summaries
+- For bug-analysis flows, structured JSON artifacts are the machine-readable source of truth, while Markdown artifacts are for human inspection
+- Runs workflow stages like `bug-analyze`, `bug-fix`, `mr-description`, `plan`, `task-describe`, `implement`, `review`, `review-fix`, `test`, and `auto`
+- Persists compact `auto` pipeline state on disk so runs can resume without storing large agent outputs
 - Uses Docker runtime services for isolated Codex execution and build verification
 
 ## Architecture
 
-The CLI now uses an executor-based architecture.
+The CLI now uses an executor + node + declarative flow architecture.
 
-- `src/index.ts` remains the orchestration layer for CLI commands and `auto` state transitions
-- `src/executors/` contains first-class executors for external actions such as Jira fetch, local Codex, Docker Codex, Claude, Claude summaries, process execution, and build verification
-- `src/executors/configs/` contains data-only default configs for executors with JSON-compatible structure
+- `src/index.ts` remains the CLI entrypoint and high-level orchestration layer
+- `src/executors/` contains first-class executors for external actions such as Jira fetch, local Codex, Docker-based build verification, Claude, Claude summaries, and process execution
+- `src/pipeline/nodes/` contains reusable runtime nodes built on top of executors
+- `src/pipeline/flow-specs/` contains declarative JSON flow specs for `preflight`, `bug-analyze`, `bug-fix`, `mr-description`, `plan`, `task-describe`, `implement`, `review`, `review-fix`, `test`, `test-fix`, `test-linter-fix`, `run-tests-loop`, `run-linter-loop`, and `auto`
 - `src/runtime/` contains shared runtime services such as command resolution, Docker runtime environment setup, and subprocess execution
 
-This keeps command handlers focused on workflow composition instead of inline subprocess wiring.
+This keeps command handlers focused on choosing a flow and providing parameters instead of assembling prompts and subprocess wiring inline.
 
 ## Repository Layout
 
 - `src/` — main TypeScript sources
 - `src/index.ts` — CLI entrypoint and workflow orchestration
+- `src/pipeline/flow-specs/` — declarative JSON specs for workflow stages
+- `src/pipeline/nodes/` — reusable pipeline nodes executed by the declarative runner
 - `src/interactive-ui.ts` — interactive TUI built with `neo-blessed`
 - `src/markdown.ts` — markdown-to-terminal renderer for the TUI
 - `src/executors/` — executor modules for concrete execution families
@@ -38,7 +42,9 @@ This keeps command handlers focused on workflow composition instead of inline su
 - `src/runtime/` — shared runtime services used by executors
 - `docker-compose.yml` — runtime services for Codex and build verification
 - `Dockerfile.codex` — container image for Codex runtime
-- `verify_build.sh` — project-specific verification entrypoint used by `verify-build`
+- `verify_build.sh` — aggregated verification entrypoint used by `verify-build`
+- `run_tests.sh` — isolated test and coverage verification entrypoint
+- `run_linter.sh` — isolated generate + lint verification entrypoint
 - `package.json` — npm package metadata and scripts
 - `tsconfig.json` — TypeScript configuration
 
@@ -47,7 +53,7 @@ This keeps command handlers focused on workflow composition instead of inline su
 - Node.js `>= 18.19.0`
 - npm
 - Docker with `docker compose` or `docker-compose`
-- `codex` CLI for `plan` and Codex-driven steps
+- `codex` CLI for `bug-analyze`, `bug-fix`, `mr-description`, `plan`, and other Codex-driven steps
 - `claude` CLI for review and summary steps
 
 ## Installation
@@ -84,9 +90,8 @@ Common optional variables:
 - `DOCKER_COMPOSE_BIN` — override compose command, for example `docker compose`
 - `CODEX_BIN` — override `codex` executable path
 - `CLAUDE_BIN` — override `claude` executable path
-- `CODEX_MODEL` — defaults to `gpt-5.4`
-- `CLAUDE_REVIEW_MODEL` — defaults to `opus`
-- `CLAUDE_SUMMARY_MODEL` — defaults to `haiku`
+- `CODEX_MODEL` — fallback model for Codex executors when the flow spec does not set `params.model`
+- `CLAUDE_MODEL` — fallback Claude model when the flow spec does not set `params.model`
 
 Example `.env`:
 
@@ -97,8 +102,7 @@ AGENTWEAVER_HOME=/absolute/path/to/AgentWeaver
 CODEX_BIN=codex
 CLAUDE_BIN=claude
 CODEX_MODEL=gpt-5.4
-CLAUDE_REVIEW_MODEL=opus
-CLAUDE_SUMMARY_MODEL=haiku
+CLAUDE_MODEL=opus
 GOPRIVATE=gitlab.example.org/*
 GONOSUMDB=gitlab.example.org/*
 GONOPROXY=gitlab.example.org/*
@@ -111,8 +115,14 @@ Direct CLI usage:
 
 ```bash
 agentweaver plan DEMO-3288
+agentweaver bug-analyze DEMO-3288
+agentweaver bug-fix DEMO-3288
+agentweaver mr-description DEMO-3288
+agentweaver task-describe DEMO-3288
 agentweaver implement DEMO-3288
 agentweaver review DEMO-3288
+agentweaver run-tests-loop DEMO-3288
+agentweaver run-linter-loop DEMO-3288
 agentweaver auto DEMO-3288
 ```
 
@@ -120,6 +130,10 @@ From source checkout:
 
 ```bash
 node dist/index.js plan DEMO-3288
+node dist/index.js bug-analyze DEMO-3288
+node dist/index.js bug-fix DEMO-3288
+node dist/index.js mr-description DEMO-3288
+node dist/index.js task-describe DEMO-3288
 node dist/index.js auto DEMO-3288
 ```
 
@@ -144,28 +158,35 @@ agentweaver auto-status DEMO-3288
 agentweaver auto-reset DEMO-3288
 ```
 
+Notes:
+
+- `--verbose` streams child process `stdout/stderr` in direct CLI mode
+- the interactive `Activity` pane is intentionally structured: it shows launch separators, prompts, summaries, and short status messages instead of raw Codex/Claude logs by default
+
 ## Interactive TUI
 
 Interactive mode opens a full-screen terminal UI with:
 
-- command input
+- flow list
+- current flow progress
 - activity log
 - task summary pane
-- command list/help
 - keyboard navigation between panes
 
 Current navigation:
 
-- `Enter` — run command
+- `Enter` — run selected flow
 - `Tab` / `Shift+Tab` — switch panes
-- `Ctrl+J` — focus activity log
-- `Ctrl+K` — focus command input
-- `Ctrl+U` — focus task summary
-- `Ctrl+H` — focus commands pane
 - `PgUp` / `PgDn` / `Home` / `End` — scroll focused panes
-- `?` or `F1` — help overlay
+- `h` — help overlay
 - `q` or `Ctrl+C` — exit
 
+Activity pane behavior:
+
+- each external launch is separated with a framed block that shows the current `node`, `executor`, and `model` when available
+- prompts and summaries are rendered as plain text for readability
+- live raw Codex/Claude output is not shown there in normal mode
+
 ## Docker Runtime
 
 Docker is used as an isolated execution environment for Codex and build/test verification.
@@ -175,6 +196,8 @@ Main services:
 - `codex` — interactive Codex container
 - `codex-exec` — non-interactive `codex exec`
 - `verify-build` — project verification script inside container
+- `run-tests` — isolated `run_tests.sh` execution inside container
+- `run-linter` — isolated `run_linter.sh` execution inside container
 - `codex-login` — interactive login container
 - `dockerd` — internal Docker daemon for testcontainers/build flows
 
@@ -204,6 +227,18 @@ Build verification:
 PROJECT_DIR="$PWD" docker compose -f "$AGENTWEAVER_HOME/docker-compose.yml" run --rm verify-build
 ```
 
+Tests only:
+
+```bash
+PROJECT_DIR="$PWD" docker compose -f "$AGENTWEAVER_HOME/docker-compose.yml" run --rm run-tests
+```
+
+Linter only:
+
+```bash
+PROJECT_DIR="$PWD" docker compose -f "$AGENTWEAVER_HOME/docker-compose.yml" run --rm run-linter
+```
+
 ## Development
 
 Install dependencies and build:

package/dist/artifacts.js

@@ -1,10 +1,23 @@
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
 import { TaskRunnerError } from "./errors.js";
 export const REVIEW_FILE_RE = /^review-(.+)-(\d+)\.md$/;
 export const REVIEW_REPLY_FILE_RE = /^review-reply-(.+)-(\d+)\.md$/;
 export const READY_TO_MERGE_FILE = "ready-to-merge.md";
+export function taskWorkspaceDir(taskKey) {
+    return path.join(process.cwd(), `.agentweaver-${taskKey}`);
+}
+export function ensureTaskWorkspaceDir(taskKey) {
+    const workspaceDir = taskWorkspaceDir(taskKey);
+    mkdirSync(workspaceDir, { recursive: true });
+    return workspaceDir;
+}
+export function taskWorkspaceFile(taskKey, fileName) {
+    return path.join(taskWorkspaceDir(taskKey), fileName);
+}
 export function artifactFile(prefix, taskKey, iteration) {
-    return `${prefix}-${taskKey}-${iteration}.md`;
+    return taskWorkspaceFile(taskKey, `${prefix}-${taskKey}-${iteration}.md`);
 }
 export function designFile(taskKey) {
     return artifactFile("design", taskKey, 1);
@@ -12,15 +25,58 @@ export function designFile(taskKey) {
 export function planFile(taskKey) {
     return artifactFile("plan", taskKey, 1);
 }
+export function bugAnalyzeFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `bug-analyze-${taskKey}.md`);
+}
+export function bugAnalyzeJsonFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `bug-analyze-${taskKey}.json`);
+}
+export function bugFixDesignFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `bug-fix-design-${taskKey}.md`);
+}
+export function bugFixDesignJsonFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `bug-fix-design-${taskKey}.json`);
+}
+export function bugFixPlanFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `bug-fix-plan-${taskKey}.md`);
+}
+export function bugFixPlanJsonFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `bug-fix-plan-${taskKey}.json`);
+}
 export function qaFile(taskKey) {
     return artifactFile("qa", taskKey, 1);
 }
 export function taskSummaryFile(taskKey) {
     return artifactFile("task", taskKey, 1);
 }
+export function readyToMergeFile(taskKey) {
+    return taskWorkspaceFile(taskKey, READY_TO_MERGE_FILE);
+}
+export function jiraTaskFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `${taskKey}.json`);
+}
+export function jiraDescriptionFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `jira-${taskKey}-description.md`);
+}
+export function mrDescriptionFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `mr-description-${taskKey}.md`);
+}
+export function autoStateFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `.agentweaver-state-${taskKey}.json`);
+}
 export function planArtifacts(taskKey) {
     return [designFile(taskKey), planFile(taskKey), qaFile(taskKey)];
 }
+export function bugAnalyzeArtifacts(taskKey) {
+    return [
+        bugAnalyzeFile(taskKey),
+        bugAnalyzeJsonFile(taskKey),
+        bugFixDesignFile(taskKey),
+        bugFixDesignJsonFile(taskKey),
+        bugFixPlanFile(taskKey),
+        bugFixPlanJsonFile(taskKey),
+    ];
+}
 export function requireArtifacts(paths, message) {
     const missing = paths.filter((filePath) => !existsSync(filePath));
     if (missing.length > 0) {

package/dist/executors/claude-executor.js

@@ -1,7 +1,17 @@
 import { claudeExecutorDefaultConfig } from "./configs/claude-config.js";
 import { processExecutor } from "./process-executor.js";
 function resolveModel(config, env) {
-    return env[config.modelEnvVar]?.trim() || config.defaultModel;
+    const primaryModel = env[config.modelEnvVar]?.trim();
+    if (primaryModel) {
+        return primaryModel;
+    }
+    for (const envVarName of config.legacyModelEnvVars ?? []) {
+        const legacyModel = env[envVarName]?.trim();
+        if (legacyModel) {
+            return legacyModel;
+        }
+    }
+    return config.defaultModel;
 }
 export const claudeExecutor = {
     kind: "claude",
@@ -10,7 +20,7 @@ export const claudeExecutor = {
     async execute(context, input, config) {
         const env = input.env ?? context.env;
         const command = input.command ?? context.runtime.resolveCmd(config.defaultCommand, config.commandEnvVar);
-        const model = resolveModel(config, env);
+        const model = input.model?.trim() || resolveModel(config, env);
         const argv = [command, "--model", model, config.promptFlag, `--allowedTools=${config.allowedTools}`];
         if (config.outputFormat) {
             argv.push("--output-format", config.outputFormat);

package/dist/executors/claude-summary-executor.js

@@ -12,7 +12,7 @@ export const claudeSummaryExecutor = {
     async execute(context, input, config) {
         const env = input.env ?? context.env;
         const command = input.command ?? context.runtime.resolveCmd(config.defaultCommand, config.commandEnvVar);
-        const model = resolveModel(config, env);
+        const model = input.model?.trim() || resolveModel(config, env);
         const argv = [command, "--model", model, config.promptFlag, `--allowedTools=${config.allowedTools}`, input.prompt];
         const processInput = {
             argv,

package/dist/executors/codex-docker-executor.js

@@ -10,7 +10,7 @@ export const codexDockerExecutor = {
     async execute(context, input, config) {
         const composeCommand = context.runtime.resolveDockerComposeCmd();
         const env = context.runtime.dockerRuntimeEnv();
-        const model = resolveModel(config, env);
+        const model = input.model?.trim() || resolveModel(config, env);
         env[config.promptEnvVar] = input.prompt;
         env[config.flagsEnvVar] = config.execFlagsTemplate.replace("{model}", model);
         const result = await processExecutor.execute(context, {

package/dist/executors/codex-local-executor.js

@@ -10,7 +10,7 @@ export const codexLocalExecutor = {
     async execute(context, input, config) {
         const env = input.env ?? context.env;
         const command = input.command ?? context.runtime.resolveCmd(config.defaultCommand, config.commandEnvVar);
-        const model = resolveModel(config, env);
+        const model = input.model?.trim() || resolveModel(config, env);
         const result = await processExecutor.execute(context, {
             argv: [command, config.subcommand, "--model", model, config.fullAutoFlag, input.prompt],
             env,

package/dist/executors/configs/claude-config.js

@@ -1,7 +1,8 @@
 export const claudeExecutorDefaultConfig = {
     commandEnvVar: "CLAUDE_BIN",
     defaultCommand: "claude",
-    modelEnvVar: "CLAUDE_REVIEW_MODEL",
+    modelEnvVar: "CLAUDE_MODEL",
+    legacyModelEnvVars: ["CLAUDE_REVIEW_MODEL"],
     defaultModel: "opus",
     promptFlag: "-p",
     allowedTools: "Read,Write,Edit",

package/dist/executors/verify-build-executor.js

@@ -1,22 +1,123 @@
 import { verifyBuildExecutorDefaultConfig } from "./configs/verify-build-config.js";
+import { TaskRunnerError } from "../errors.js";
 import { processExecutor } from "./process-executor.js";
+function parseStructuredResult(output, service) {
+    const lines = output
+        .split(/\r?\n/)
+        .map((line) => line.replace(/\u001b\[[0-9;]*m/g, "").trim())
+        .filter(Boolean);
+    if (lines.length === 0) {
+        throw new TaskRunnerError(`Structured result is missing from service '${service}' output.`);
+    }
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const line = lines[index];
+        if (!line) {
+            continue;
+        }
+        const candidates = [];
+        if (line.startsWith("{") && line.endsWith("}")) {
+            candidates.push(line);
+        }
+        const firstBrace = line.indexOf("{");
+        const lastBrace = line.lastIndexOf("}");
+        if (firstBrace >= 0 && lastBrace > firstBrace) {
+            const slice = line.slice(firstBrace, lastBrace + 1).trim();
+            if (slice && !candidates.includes(slice)) {
+                candidates.push(slice);
+            }
+        }
+        for (const rawJson of candidates) {
+            let parsed;
+            try {
+                parsed = JSON.parse(rawJson);
+            }
+            catch {
+                continue;
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                continue;
+            }
+            const candidate = parsed;
+            if (typeof candidate.ok !== "boolean" ||
+                typeof candidate.kind !== "string" ||
+                typeof candidate.stage !== "string" ||
+                typeof candidate.exitCode !== "number" ||
+                typeof candidate.summary !== "string" ||
+                typeof candidate.command !== "string") {
+                continue;
+            }
+            const details = candidate.details;
+            if (details !== undefined && (!details || typeof details !== "object" || Array.isArray(details))) {
+                continue;
+            }
+            return {
+                ok: candidate.ok,
+                kind: candidate.kind,
+                stage: candidate.stage,
+                exitCode: candidate.exitCode,
+                summary: candidate.summary,
+                command: candidate.command,
+                details: details ?? {},
+            };
+        }
+    }
+    throw new TaskRunnerError(`Structured result is missing or invalid in service '${service}' output.`);
+}
 export const verifyBuildExecutor = {
     kind: "verify-build",
     version: 1,
     defaultConfig: verifyBuildExecutorDefaultConfig,
     async execute(context, input, config) {
         const composeCommand = context.runtime.resolveDockerComposeCmd();
-        const result = await processExecutor.execute(context, {
-            argv: [...composeCommand, config.composeFileFlag, input.dockerComposeFile, ...config.runArgs, config.service],
-            env: context.runtime.dockerRuntimeEnv(),
-            verbose: config.verbose,
-            label: config.service,
-        }, {
-            printFailureOutput: config.printFailureOutput,
-        });
+        const service = input.service ?? config.service;
+        if (context.dryRun) {
+            await processExecutor.execute(context, {
+                argv: [...composeCommand, config.composeFileFlag, input.dockerComposeFile, ...config.runArgs, service],
+                env: context.runtime.dockerRuntimeEnv(),
+                verbose: config.verbose,
+                label: service,
+            }, {
+                printFailureOutput: config.printFailureOutput,
+            });
+            return {
+                output: "",
+                composeCommand,
+                parsed: {
+                    ok: true,
+                    kind: service,
+                    stage: "dry_run",
+                    exitCode: 0,
+                    summary: `Dry run for service '${service}'`,
+                    command: [...composeCommand, config.composeFileFlag, input.dockerComposeFile, ...config.runArgs, service].join(" "),
+                    details: {},
+                },
+            };
+        }
+        let output = "";
+        let exitCode = 0;
+        try {
+            const result = await processExecutor.execute(context, {
+                argv: [...composeCommand, config.composeFileFlag, input.dockerComposeFile, ...config.runArgs, service],
+                env: context.runtime.dockerRuntimeEnv(),
+                verbose: config.verbose,
+                label: service,
+            }, {
+                printFailureOutput: config.printFailureOutput,
+            });
+            output = result.output;
+        }
+        catch (error) {
+            output = String(error.output ?? "");
+            exitCode = Number(error.returnCode ?? 1);
+        }
+        const parsed = parseStructuredResult(output, service);
+        if (parsed.exitCode !== exitCode && exitCode !== 0) {
+            throw new TaskRunnerError(`Structured result exit code mismatch for service '${service}': script=${parsed.exitCode}, runtime=${exitCode}.`);
+        }
         return {
-            output: result.output,
+            output,
             composeCommand,
+            parsed,
         };
     },
 };