fullstack-agentic-flow 2.0.0

package/dist/src/io/paths.js

@@ -0,0 +1,6 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+/** Compiled location is dist/src/io/paths.js; the payload ships at the package root. */
+const here = dirname(fileURLToPath(import.meta.url));
+export const PACKAGE_ROOT = join(here, '..', '..', '..');
+export const PAYLOAD_DIR = join(PACKAGE_ROOT, 'payload');

package/dist/src/io/shell.js

@@ -0,0 +1,25 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+/** True when `name` resolves on PATH (honours PATHEXT on Windows). */
+export function onPath(name) {
+    const extensions = process.platform === 'win32' ? (process.env['PATHEXT'] ?? '.EXE;.CMD;.BAT').split(';') : [''];
+    const dirs = (process.env['PATH'] ?? '').split(delimiter).filter((dir) => dir.length > 0);
+    return dirs.some((dir) => extensions.some((ext) => existsSync(join(dir, `${name}${ext}`))));
+}
+export class ShellResult {
+    command;
+    exitCode;
+    constructor(command, exitCode) {
+        this.command = command;
+        this.exitCode = exitCode;
+    }
+    get succeeded() {
+        return this.exitCode === 0;
+    }
+}
+/** Runs a documented install command in the target repo, attached to the terminal. */
+export function runShell(command, cwd) {
+    const result = spawnSync(command, { cwd, shell: true, stdio: 'inherit' });
+    return new ShellResult(command, result.status ?? 1);
+}

package/dist/src/registry/commands.js

@@ -0,0 +1,52 @@
+/** A pipeline slash command. Its body lives in payload/commands/{slug}.md and is runtime-neutral. */
+export class PipelineCommand {
+    slug;
+    description;
+    agentFiles;
+    triggers;
+    constructor(slug, description, 
+    /** Agent instruction files (in .ai-agents/agents/) this command dispatches to. */
+    agentFiles, 
+    /** Phrases that should make a Codex skill trigger, besides the slash form. */
+    triggers) {
+        this.slug = slug;
+        this.description = description;
+        this.agentFiles = agentFiles;
+        this.triggers = triggers;
+    }
+}
+const COMMANDS = [
+    new PipelineCommand('scaffold', 'Establish conventions in an empty repo: one real vertical slice in the backend canon, test-first — run before /bootstrap', ['00a-scaffold.md'], 'starting a new project or empty repository'),
+    new PipelineCommand('bootstrap', "Generate this repository's architecture-context.md (topology, canon mapping, rules) — run once before anything else", ['00-bootstrap.md'], 'setting up the pipeline on an existing codebase'),
+    new PipelineCommand('scaffold-module', 'Create the canon skeleton for a new backend module (registration, layer folders, boot test)', ['00b-module-scaffold.md'], 'adding a new backend module'),
+    new PipelineCommand('intake', 'Start a new feature — gathers requirements conversationally, business language only', ['01-intake.md'], 'starting a new feature'),
+    new PipelineCommand('impact', 'Measure how much of the system a feature disturbs and set its risk class (--verify after implementation)', ['01b-impact-analysis.md'], 'asking how risky or how big a change is'),
+    new PipelineCommand('contract', 'Run dependency map, backend contract and UI contract in parallel, then freeze the interface seam', ['02a-dependency-map.md', '02b-backend-contract.md', '02c-ui-contract.md', '02d-interface-seam.md'], 'designing an approved feature'),
+    new PipelineCommand('seam', 'Export or import cross-repository contracts for split backend/frontend repos', ['02d-interface-seam.md'], 'syncing an API contract between repositories'),
+    new PipelineCommand('sequence', 'Break approved contracts into ordered, test-first tasks — both tracks in parallel', ['03a-backend-sequence.md', '03b-ui-sequence.md'], 'planning tasks after contracts are approved'),
+    new PipelineCommand('implement', 'Execute the next pending task test-first — one task, one commit, then stop', ['04a-backend-implementer.md', '04b-ui-implementer.md', '00b-module-scaffold.md'], 'implementing the next task'),
+    new PipelineCommand('qa', 'Generate the QA spec for the finished branch, before it merges — both tracks', ['06-qa-spec.md'], 'writing a QA or test plan for a finished feature branch'),
+    new PipelineCommand('security', 'Audit the branch diff for security issues before merging — both tracks', ['07-security.md'], 'security review of a feature branch'),
+    new PipelineCommand('perf', 'Audit the branch for performance problems before merging (mandatory for risk class L2+)', ['08-performance.md'], 'performance review of a feature branch'),
+    new PipelineCommand('finalize', "Close the feature on its branch: release note, archive, state reset — so nothing is left to do after the merge", ['09a-feature-notes.md'], 'finishing a feature branch after Gate 3'),
+    new PipelineCommand('release', 'Assemble the changelog from the features\' release notes and run the retrospective', ['09b-release.md'], 'cutting a release'),
+    new PipelineCommand('status', 'Dashboard — current feature, risk class, both tracks, open gate, next action', [], 'asking where the pipeline is'),
+    new PipelineCommand('resume', 'Resume from wherever this feature stopped', [], 'coming back to unfinished pipeline work'),
+];
+export class CommandCatalog {
+    commands;
+    constructor(commands) {
+        this.commands = commands;
+    }
+    all() {
+        return this.commands;
+    }
+    bySlug(slug) {
+        const command = this.commands.find((candidate) => candidate.slug === slug);
+        if (command === undefined) {
+            throw new Error(`Command /${slug} is not in the catalog`);
+        }
+        return command;
+    }
+}
+export const COMMAND_CATALOG = new CommandCatalog(COMMANDS);

package/dist/src/registry/subagents.js

@@ -0,0 +1,52 @@
+/** A Claude Code subagent registration: a thin pointer at the real instructions. */
+export class SubagentDefinition {
+    name;
+    description;
+    agentFile;
+    requiresContext;
+    constructor(name, description, agentFile, 
+    /** False only for agents that run before architecture-context.md can exist. */
+    requiresContext) {
+        this.name = name;
+        this.description = description;
+        this.agentFile = agentFile;
+        this.requiresContext = requiresContext;
+    }
+}
+const SUBAGENTS = [
+    new SubagentDefinition('scaffold', "Establish a new repository's conventions by building one real, thin vertical slice in the backend canon, test-first, so architecture-context.md can be derived from real code. Run before bootstrap on empty or near-empty repos.", '00a-scaffold.md', false),
+    new SubagentDefinition('bootstrap', "Generate this repository's architecture-context.md by scanning the codebase (using the code graphs when installed) and interviewing the developer. Records topology and canon mapping.", '00-bootstrap.md', false),
+    new SubagentDefinition('module-scaffold', 'Create the empty canon skeleton for a new backend module — registration, layer directories, route file, test directories and one boot test. No behaviour.', '00b-module-scaffold.md', true),
+    new SubagentDefinition('intake', 'Requirements intake for a new feature. Gathers the business need conversationally and writes state/current-feature.md.', '01-intake.md', true),
+    new SubagentDefinition('impact-analysis', 'Measure the blast radius of a feature with the code graphs, score ten risk dimensions, and set the risk class (predict); compare the actual diff with the prediction (verify).', '01b-impact-analysis.md', true),
+    new SubagentDefinition('dependency-map', "Map the feature's footprint across existing backend and frontend code, verified file by file. Runs in parallel with the two contract agents.", '02a-dependency-map.md', true),
+    new SubagentDefinition('backend-contract', 'Specify how the backend will be built — canon placement, named Data classes, use cases, the interface surface for the topology, and a test-first plan.', '02b-backend-contract.md', true),
+    new SubagentDefinition('ui-contract', 'Specify how the interface will be built — screens, composition, every required state, forms, interaction, responsive, accessibility, and named consumed types.', '02c-ui-contract.md', true),
+    new SubagentDefinition('interface-seam', 'Reconcile what the backend promises against what the UI consumes — API, GraphQL, MVC page contracts, or cross-repo contracts — and freeze it.', '02d-interface-seam.md', true),
+    new SubagentDefinition('backend-sequence', 'Break the approved backend contract into ordered single-commit, test-first tasks in canon order.', '03a-backend-sequence.md', true),
+    new SubagentDefinition('ui-sequence', 'Break the approved UI contract into ordered single-commit, test-first tasks, each screen with all its required states.', '03b-ui-sequence.md', true),
+    new SubagentDefinition('backend-implementer', 'Execute the next pending backend task with the TDD loop and commit it. Exactly one task per invocation.', '04a-backend-implementer.md', true),
+    new SubagentDefinition('ui-implementer', 'Execute the next pending UI task with the TDD loop and commit it. Approved components only, every required state. One task per invocation.', '04b-ui-implementer.md', true),
+    new SubagentDefinition('qa-spec', 'Produce the QA specification for a finished feature branch before it merges, using the impact regression scope, every UI state, the role matrix, and seam conformance.', '06-qa-spec.md', true),
+    new SubagentDefinition('security-review', "Audit a feature branch's diff for security issues across backend and frontend before it merges, against the intake's role matrix. Critical findings block the merge.", '07-security.md', true),
+    new SubagentDefinition('performance-review', "Audit a feature branch for performance problems before it merges, judged against the project's stated scale. Mandatory for risk class L2+.", '08-performance.md', true),
+    new SubagentDefinition('feature-notes', 'Close a feature on its branch after Gate 3: write its release note as a changeset, archive the contracts and reasoning, and reset the state directory.', '09a-feature-notes.md', true),
+    new SubagentDefinition('release-notes', "Assemble a release changelog from the features' changesets and run the observations retrospective. Release administration, not feature work.", '09b-release.md', true),
+];
+export class SubagentCatalog {
+    subagents;
+    constructor(subagents) {
+        this.subagents = subagents;
+    }
+    all() {
+        return this.subagents;
+    }
+    byName(name) {
+        const agent = this.subagents.find((candidate) => candidate.name === name);
+        if (agent === undefined) {
+            throw new Error(`Subagent ${name} is not in the catalog`);
+        }
+        return agent;
+    }
+}
+export const SUBAGENT_CATALOG = new SubagentCatalog(SUBAGENTS);

package/dist/src/registry/tools.js

@@ -0,0 +1,99 @@
+import { Runtime } from '../domain/runtime.js';
+import { ExternalTool, InstallStep, ProbeKind, RuntimeSupport, StepLocation, ToolId, ToolProbe, ToolRole, } from '../domain/tool.js';
+const shell = (description, command, requires, verified = true) => new InstallStep(description, command, StepLocation.Shell, requires, verified);
+const inAgent = (description, command) => new InstallStep(description, command, StepLocation.AgentUi, [], true);
+const binary = (name) => new ToolProbe(ProbeKind.Binary, [name]);
+const paths = (...targets) => new ToolProbe(ProbeKind.AnyPath, targets);
+/**
+ * Install commands are taken from each project's README as of September 2026.
+ * Steps marked `verified: false` are the closest documented equivalent; SETUP.md
+ * flags them so a human checks before relying on them.
+ */
+const TOOLS = [
+    new ExternalTool(ToolId.FindSkills, 'find-skills', 'vercel-labs/skills', ToolRole.Skill, 'Discovers installable agent skills for unfamiliar frameworks and libraries.', ['00a scaffold', '00 bootstrap'], [
+        new RuntimeSupport(Runtime.ClaudeCode, [shell('Install the find-skills skill', 'npx skills add vercel-labs/skills --skill find-skills -a claude-code -y', ['npx'])], paths('.claude/skills/find-skills', '~/.claude/skills/find-skills'), ''),
+        new RuntimeSupport(Runtime.Codex, [shell('Install the find-skills skill', 'npx skills add vercel-labs/skills --skill find-skills -a codex -y', ['npx'])], paths('.agents/skills/find-skills', '~/.codex/skills/find-skills'), ''),
+    ], [], ['Ask: "find a skill for <framework or task>". Installing what it finds is always a human decision.']),
+    new ExternalTool(ToolId.Superpowers, 'superpowers', 'obra/superpowers', ToolRole.Plugin, 'Discipline skills: test-driven-development, systematic-debugging, verification-before-completion, code review.', ['00a', '00b', '04a', '04b', 'Gate 2'], [
+        new RuntimeSupport(Runtime.ClaudeCode, [shell('Install from the official marketplace (also enabled in .claude/settings.json)', 'claude plugin install superpowers@claude-plugins-official --scope project', ['claude'])], paths('~/.claude/plugins/marketplaces/claude-plugins-official', '~/.claude/plugins/cache/claude-plugins-official'), ''),
+        new RuntimeSupport(Runtime.Codex, [inAgent('Install from the Codex plugin menu', 'In Codex: /plugins → superpowers → Install Plugin')], paths('~/.codex/plugins'), ''),
+    ], [], [
+        'Pipeline owns the workflow: brainstorming, writing-plans, executing-plans and subagent-driven-development are replaced by /intake → /contract → /sequence → /implement. See .ai-agents/toolchain.md §Precedence.',
+    ]),
+    new ExternalTool(ToolId.ClaudeMem, 'claude-mem', 'thedotmack/claude-mem', ToolRole.Plugin, 'Session memory: captures what agents did and injects relevant context into later sessions. Recall only, never truth.', ['every agent (passive)', '/resume'], [
+        new RuntimeSupport(Runtime.ClaudeCode, [shell('Install and register hooks', 'npx claude-mem install', ['npx'])], paths('~/.claude-mem'), ''),
+        new RuntimeSupport(Runtime.Codex, [shell('Install (detects Codex CLI)', 'npx claude-mem install', ['npx'])], paths('~/.claude-mem'), 'Codex support is newer than Claude Code support; check the claude-mem release notes for the current capture coverage.'),
+    ], [], ['Nothing to run. Data lives in ~/.claude-mem, outside the repo.']),
+    new ExternalTool(ToolId.Impeccable, 'impeccable', 'pbakaus/impeccable', ToolRole.Plugin, 'Design language, PRODUCT.md/DESIGN.md context, and a deterministic UI anti-pattern detector.', ['00a', '00 bootstrap', '02c', '04b', '05 CI', '06 QA'], [
+        new RuntimeSupport(Runtime.ClaudeCode, [shell('Install for detected harnesses', 'npx impeccable install', ['npx'])], paths('.impeccable', '.claude/skills/impeccable', '~/.claude/skills/impeccable'), ''),
+        new RuntimeSupport(Runtime.Codex, [shell('Install for Codex', 'npx impeccable install --providers=codex', ['npx'])], paths('.impeccable', '.agents/skills/impeccable', '~/.codex/skills/impeccable'), ''),
+    ], [], ['/impeccable init (writes PRODUCT.md) and /impeccable document (writes DESIGN.md) during /scaffold', 'npx impeccable detect <path> in CI and the UI self-check']),
+    new ExternalTool(ToolId.TaskObserver, 'task-observer', 'rebelytics/one-skill-to-rule-them-all', ToolRole.Skill, 'Watches sessions for repeated corrections and proposes skill and agent improvements. Logs to .ai-agents/observations/.', ['every agent (passive)', '09 changelog retrospective'], [
+        new RuntimeSupport(Runtime.ClaudeCode, [shell('Install the task-observer skill', 'npx skills add rebelytics/one-skill-to-rule-them-all --skill task-observer -a claude-code -y', ['npx'])], paths('.claude/skills/task-observer', '~/.claude/skills/task-observer'), ''),
+        new RuntimeSupport(Runtime.Codex, [shell('Install the community Codex port', 'npx skills add AllstarGER/one-skill-to-rule-them-all --skill task-observer -a codex -y', ['npx'])], paths('.agents/skills/task-observer', '~/.codex/skills/task-observer'), 'Community port based on an older task-observer version.'),
+    ], [], ['Activation instruction is in the pipeline section of CLAUDE.md / AGENTS.md.', 'Ask "any observations logged?" when closing a long session.']),
+    new ExternalTool(ToolId.Ponytail, 'ponytail', 'DietrichGebert/ponytail', ToolRole.Plugin, 'Least-code decision ladder and over-engineering review. Governs logic and dependencies, never types or tests.', ['02b', '02c', '04a', '04b', 'Gate 2'], [
+        new RuntimeSupport(Runtime.ClaudeCode, [
+            shell('Add the marketplace', 'claude plugin marketplace add DietrichGebert/ponytail', ['claude']),
+            shell('Install the plugin', 'claude plugin install ponytail@ponytail --scope project', ['claude']),
+        ], paths('~/.claude/plugins/marketplaces/ponytail', '~/.claude/plugins/cache/ponytail'), ''),
+        new RuntimeSupport(Runtime.Codex, [
+            shell('Add the marketplace', 'codex plugin marketplace add DietrichGebert/ponytail', ['codex']),
+            shell('Install the plugin', 'codex plugin add ponytail@ponytail', ['codex']),
+        ], paths('~/.codex/plugins'), ''),
+    ], [], ['/ponytail lite while implementing; /ponytail-review on the staged diff before Gate 2.']),
+    new ExternalTool(ToolId.Headroom, 'headroom', 'headroomlabs-ai/headroom', ToolRole.Proxy, 'Local proxy that compresses tool output, logs and files before they reach the model. Wraps the session.', ['developer, around 00 bootstrap / 02a / 06 / 07'], [
+        new RuntimeSupport(Runtime.ClaudeCode, [shell('Install the CLI', 'uv tool install --python 3.13 "headroom-ai[all]"', ['uv'])], binary('headroom'), ''),
+        new RuntimeSupport(Runtime.Codex, [shell('Install the CLI', 'uv tool install --python 3.13 "headroom-ai[all]"', ['uv'])], binary('headroom'), ''),
+    ], [], [
+        'Start sessions with: headroom wrap claude   (or: headroom wrap codex)',
+        'Wrapping routes the agent through a local base URL; check the headroom release notes for long-context caveats.',
+    ]),
+    new ExternalTool(ToolId.CodeReviewGraph, 'code-review-graph', 'tirth8205/code-review-graph', ToolRole.CodeGraph, 'Impact engine: incremental code graph with blast-radius and change-risk tools over MCP.', ['01b impact', '02a', '04a', '04b', '06', '07'], [
+        new RuntimeSupport(Runtime.ClaudeCode, [
+            shell('Install the CLI', 'uv tool install code-review-graph', ['uv']),
+            shell('Register the MCP server, hooks and skills', 'code-review-graph install --platform claude-code -y', ['code-review-graph']),
+            shell('Build the graph', 'code-review-graph build', ['code-review-graph']),
+        ], binary('code-review-graph'), ''),
+        new RuntimeSupport(Runtime.Codex, [
+            shell('Install the CLI', 'uv tool install code-review-graph', ['uv']),
+            shell('Register the MCP server, hooks and skills', 'code-review-graph install --platform codex -y', ['code-review-graph']),
+            shell('Build the graph', 'code-review-graph build', ['code-review-graph']),
+        ], binary('code-review-graph'), ''),
+    ], ['.code-review-graph/'], [
+        'Agents run `code-review-graph update` before querying when the graph is older than HEAD.',
+        'Without MCP, the same answers come from the CLI: `code-review-graph impact --base main`, `code-review-graph detect-changes`.',
+    ]),
+    new ExternalTool(ToolId.Graphify, 'graphify', 'safishamsi/graphify', ToolRole.CodeGraph, 'Architecture map: whole-repo knowledge graph across code, SQL, docs and config, with GRAPH_REPORT.md.', ['00 bootstrap', '00a', '01b', '08'], [
+        new RuntimeSupport(Runtime.ClaudeCode, [
+            shell('Install the CLI', 'uv tool install graphifyy', ['uv']),
+            shell('Install the /graphify skill', 'graphify install', ['graphify']),
+            shell('Rebuild on commit and checkout', 'graphify hook install', ['graphify']),
+        ], binary('graphify'), ''),
+        new RuntimeSupport(Runtime.Codex, [
+            shell('Install the CLI', 'uv tool install graphifyy', ['uv']),
+            shell('Install the skill for Codex', 'graphify install --platform codex', ['graphify']),
+            shell('Rebuild on commit and checkout', 'graphify hook install', ['graphify']),
+        ], binary('graphify'), ''),
+    ], ['graphify-out/'], ['/graphify . once after install; the hook keeps it current. /bootstrap reads graphify-out/GRAPH_REPORT.md first.']),
+];
+export class ToolCatalog {
+    tools;
+    constructor(tools) {
+        this.tools = tools;
+    }
+    all() {
+        return this.tools;
+    }
+    byId(id) {
+        const tool = this.tools.find((candidate) => candidate.id === id);
+        if (tool === undefined) {
+            throw new Error(`Tool ${id} is not in the catalog`);
+        }
+        return tool;
+    }
+    forIds(ids) {
+        return this.tools.filter((tool) => ids.includes(tool.id));
+    }
+}
+export const TOOL_CATALOG = new ToolCatalog(TOOLS);

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "fullstack-agentic-flow",
+  "version": "2.0.0",
+  "description": "Gated multi-agent delivery pipeline for Claude Code and Codex: MVC, unified API, and split backend/frontend topologies, TDD-first, typed data, impact analysis.",
+  "type": "module",
+  "bin": {
+    "fullstack-agentic-flow": "dist/src/cli/main.js"
+  },
+  "files": [
+    "dist/src",
+    "payload",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test \"dist/test/**/*.test.js\"",
+    "prepublishOnly": "npm test",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "agents",
+    "agent-skills",
+    "tdd",
+    "pipeline",
+    "laravel",
+    "nestjs",
+    "code-review",
+    "impact-analysis"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/mohd-arbaaz/fullstack-agentic-flow.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://gitlab.com/mohd-arbaaz/fullstack-agentic-flow#readme",
+  "bugs": {
+    "url": "https://gitlab.com/mohd-arbaaz/fullstack-agentic-flow/-/issues"
+  }
+}