devflow-agent-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mayordomoespejo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,313 @@
+# Devflow
+
+Devflow is a universal AI development workflow for real software projects.
+
+It gives you three things:
+
+- a shared workflow: `PLAN -> BUILD -> TEST -> REVIEW -> VERIFY`
+- portable prompts you can reuse in any chat, IDE, or terminal workflow
+- optional adapters that map the workflow into specific tool conventions when that mapping is clear
+
+Devflow is designed to be model-agnostic and harness-agnostic. It works with any model, including Claude, Gemini, GPT, and similar systems, without making your project depend on one vendor or one interface.
+
+## What Devflow installs
+
+Devflow has two layers:
+
+- Core: always installed
+- Adapters: optional
+
+The core is the source of truth. Adapters are thin additions on top.
+
+### Core
+
+Every installation includes:
+
+- `AGENTS.md` - universal instructions for the agent working in the repo
+- `DEVFLOW.md` - the workflow reference for `PLAN -> BUILD -> TEST -> REVIEW -> VERIFY`
+- `devflow/prompts/` - reusable prompts for `plan`, `build`, `tests`, `review`, and `verify`
+- `.devflow/workflows.yml` - optional workflow customization contract for this project
+
+This is the stable part of the product. If a user changes model or tool, the core still works.
+
+## Workflow Customization
+
+Devflow also installs an optional project file:
+
+```txt
+.devflow/workflows.yml
+```
+
+This file lets a project declare preferred workflow behavior without editing the shared prompts directly.
+
+Example uses:
+
+- define review focus areas such as bugs, regressions, missing tests, and security
+- declare what a plan should include
+- declare what verify should check before sign-off
+
+Today, `workflows.yml` is a configuration contract for:
+
+- humans working in the repository
+- agents that read project files directly
+- future Devflow versions that may interpret this config more deeply
+
+Current behavior:
+
+- Devflow installs the file as part of the core
+- you can edit it safely per project
+- the CLI does not yet parse it to rewrite prompts
+
+That is intentional. The file exists now so projects can establish stable local workflow expectations before deeper automation is added.
+
+### Adapters
+
+Adapters are optional and exist only to make the core easier to use in a specific environment.
+
+- `cursor` installs Cursor-facing command and rule files
+- `claude` installs Claude Code slash commands under `.claude/commands/`
+- `generic` installs usage instructions for any unsupported chat or IDE
+- `codex` and `gemini` install guidance under `.devflow/adapters/` without inventing unsupported config
+
+If Devflow does not know a tool's official integration format, it does not fake one.
+
+## Works With Any Model
+
+Devflow is not tied to a specific model provider.
+
+You can use the same workflow with:
+
+- Claude
+- Gemini
+- GPT
+- local models
+- any future model that can read instructions and generate code
+
+The model can change. The engineering process should not.
+
+## Installation
+
+Install into the current repository:
+
+```sh
+npx devflow-agent-cli init
+```
+
+Install with the Cursor adapter:
+
+```sh
+npx devflow-agent-cli init --adapter cursor
+```
+
+Install with the generic adapter:
+
+```sh
+npx devflow-agent-cli init --adapter generic
+```
+
+Default behavior:
+
+- if the target already uses `.cursor/`, Devflow defaults to `cursor`
+- otherwise Devflow defaults to `generic`
+
+Useful flags:
+
+- `--target <path>` installs into another directory
+- `--merge` keeps existing files and only adds missing Devflow-managed files
+- `--force` overwrites only Devflow-managed paths: `AGENTS.md`, `DEVFLOW.md`, `devflow/`, `.cursor/`, `.devflow/`
+- `--dry-run` previews what would change
+
+## Plugins
+
+Plugins extend Devflow with additional workflow capabilities beyond the built-in adapters. Where adapters connect Devflow to AI tools, plugins add new integrations: CI configuration, security audits, company-specific rules, and more.
+
+```sh
+# Install a plugin from npm
+npx devflow-agent-cli add devflow-plugin-github
+
+# Install from a local path
+npx devflow-agent-cli add ./path/to/my-plugin
+
+# Remove a plugin
+npx devflow-agent-cli remove plugin-name
+```
+
+Installed plugins are tracked in `.devflow/plugins.yml` and their health is reported by `devflow doctor`. See [docs/plugins.md](docs/plugins.md) and [docs/plugin-authoring.md](docs/plugin-authoring.md) for full details.
+
+---
+
+## Doctor
+
+Use `devflow doctor` to inspect the current repository or another target and report:
+
+- whether the core is installed correctly
+- which adapters and plugins are present
+- missing files
+- recommended next commands
+
+Examples:
+
+```sh
+npx devflow-agent-cli doctor
+npx devflow-agent-cli doctor --target ../other-repo
+npx devflow-agent-cli doctor --json
+```
+
+Useful flags:
+
+- `--target <path>` inspects another directory
+- `--json` prints JSON only
+- `--verbose` includes adapter-level missing files
+- `--fix` prints safe fix guidance without making destructive changes
+
+## Explain
+
+Use `devflow explain` to show what Devflow has installed in a repository and where the working rules come from.
+
+It reports:
+
+- CLI version
+- installed core files and adapters
+- available workflows such as `plan`, `tests`, `review`, and `verify`
+- the project files that define Devflow behavior
+
+Examples:
+
+```sh
+npx devflow-agent-cli explain
+npx devflow-agent-cli explain --target ../other-repo
+npx devflow-agent-cli explain --json
+```
+
+Useful flags:
+
+- `--target <path>` inspects another directory
+- `--json` prints JSON only
+- `--verbose` includes exact source paths and adapter checks
+
+## Quick Start In 30 Seconds
+
+1. Run:
+
+```sh
+npx devflow-agent-cli init
+```
+
+2. Open the installed files:
+
+- `AGENTS.md`
+- `DEVFLOW.md`
+- `devflow/prompts/plan.txt`
+
+3. Start every non-trivial task with the workflow:
+
+- `PLAN` - understand the task, touched files, tests, and risks
+- `BUILD` - implement the smallest correct change
+- `TEST` - cover happy path, edge cases, and failures
+- `REVIEW` - inspect for bugs, security issues, duplication, and unnecessary complexity
+- `VERIFY` - confirm the result matches the plan and is ready to ship
+
+4. If your tool supports native commands, install an adapter. If not, copy the prompts into your normal chat or IDE flow.
+
+That is the whole point of Devflow: one process, many tools.
+
+## How Adapters Work
+
+Adapters do not replace the core. They only package it for a specific environment.
+
+Current adapter model:
+
+| Adapter | Type | Installed path |
+| --- | --- | --- |
+| `cursor` | config-backed adapter | `.cursor/commands/`, `.cursor/rules/` |
+| `claude` | config-backed adapter | `.claude/commands/` |
+| `generic` | documentation adapter | `.devflow/README.md` |
+| `codex` | documentation adapter | `.devflow/adapters/codex/README.md` |
+| `gemini` | documentation adapter | `.devflow/adapters/gemini/README.md` |
+
+This keeps the product honest:
+
+- the workflow is universal
+- integrations are optional
+- unsupported formats stay as documentation until there is a clear contract
+
+## Why This Exists
+
+AI-assisted development often degrades because teams keep changing prompts, models, and tools without keeping the engineering process stable.
+
+Typical failure modes:
+
+- coding starts before the problem is understood
+- tests are skipped or generated too late
+- review becomes optional
+- quality depends on the current chat session
+- every repository grows its own inconsistent prompt folklore
+
+Devflow gives the repo a stable process instead of relying on one person's memory or one tool's defaults.
+
+## Repository Structure
+
+```txt
+src/             TypeScript source modules
+dist/            Compiled output (generated by tsc)
+templates/
+  core/          Core files installed by every init
+  adapters/      Adapter files (cursor, claude, generic, ...)
+scripts/         Build validation, smoke tests, unit tests
+docs/            User guides
+examples/        Sample projects and usage examples
+```
+
+`templates/` is the source of truth for what `devflow init` installs.
+
+## Roadmap
+
+Near term:
+
+- keep the core stable and minimal
+- improve adapter documentation quality
+- harden CLI validation and smoke coverage
+- align docs and examples around the same contract
+
+Later, if clearly supported by each tool:
+
+- add more config-backed adapters only when the integration format is verified
+- improve adapter auto-detection where it is low-risk
+- expand prompt packs for common repo workflows without bloating the core
+
+Not planned:
+
+- vendor lock-in
+- model-specific workflow forks
+- hidden automation that rewrites arbitrary project files
+
+## Verification
+
+Run the local checks:
+
+```sh
+npm test
+```
+
+This validates the template contract and runs the CLI smoke test.
+
+## Releases
+
+- Current version: `0.1.0`
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Security policy: [SECURITY.md](SECURITY.md)
+
+## Tool Guides
+
+- [Anywhere](docs/anywhere.md)
+- [Cursor](docs/cursor.md)
+- [Claude Code](docs/claude.md)
+- [Codex](docs/codex.md)
+- [Monorepo setup](docs/monorepo.md)
+- [Plugins](docs/plugins.md)
+- [Plugin authoring](docs/plugin-authoring.md)
+
+## License
+
+MIT

package/bin/devflow.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli');

package/dist/cli.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const constants_1 = require("./constants");
+const init_1 = require("./commands/init");
+const doctor_1 = require("./commands/doctor");
+const explain_1 = require("./commands/explain");
+const add_1 = require("./commands/add");
+const pkg = require('../package.json');
+commander_1.program
+    .name('devflow')
+    .description('Universal AI development workflow toolkit — install the core plus optional adapters')
+    .version(pkg.version, '-v, --version');
+commander_1.program
+    .command('init')
+    .description('Install Devflow core and optional adapters into the current project')
+    .option('-f, --force', 'overwrite existing Devflow-managed files')
+    .option('-m, --merge', 'install only files that do not yet exist (skip conflicts)')
+    .option('-n, --dry-run', 'preview operations without writing')
+    .option('-t, --target <path>', 'install into a different directory', process.cwd())
+    .option('--adapter <adapter>', `single adapter: ${constants_1.ALL_ADAPTERS.join(', ')}, none (default: cursor if .cursor exists, claude if .claude exists, otherwise generic)`)
+    .option('--adapters <adapters>', `comma-separated adapters: ${constants_1.ALL_ADAPTERS.join(', ')}, none, all`)
+    .option('--tool <tools>', 'deprecated alias for --adapter')
+    .action(init_1.runInit);
+commander_1.program
+    .command('doctor')
+    .description('Diagnose the Devflow installation in the current project or another target')
+    .option('-t, --target <path>', 'inspect a different directory', process.cwd())
+    .option('-j, --json', 'output JSON only')
+    .option('-f, --fix', 'show safe fix guidance when issues are found')
+    .option('--verbose', 'include adapter details and missing files')
+    .action(doctor_1.runDoctor);
+commander_1.program
+    .command('explain')
+    .description('Explain what parts of Devflow are installed and where the project rules come from')
+    .option('-t, --target <path>', 'inspect a different directory', process.cwd())
+    .option('-j, --json', 'output JSON only')
+    .option('--verbose', 'include exact paths and extra checks')
+    .action(explain_1.runExplain);
+commander_1.program
+    .command('add <source>')
+    .description('Install a Devflow plugin from a local path or npm package')
+    .option('-f, --force', 'reinstall even if the plugin is already present')
+    .option('-n, --dry-run', 'preview operations without writing')
+    .option('-t, --target <path>', 'install into a different directory', process.cwd())
+    .action(add_1.runAdd);
+commander_1.program
+    .command('remove <name>')
+    .description('Remove an installed Devflow plugin')
+    .option('-t, --target <path>', 'target directory containing the plugin', process.cwd())
+    .action(add_1.runRemove);
+commander_1.program.parse(process.argv);

package/dist/commands/add.js

@@ -0,0 +1,137 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAdd = runAdd;
+exports.runRemove = runRemove;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const install_1 = require("../install");
+const plugins_1 = require("../plugins");
+function runAdd(source, options) {
+    const targetDir = (0, install_1.resolveTarget)(options.target ?? process.cwd());
+    const dryRun = Boolean(options.dryRun);
+    const force = Boolean(options.force);
+    // Resolve source → local plugin directory
+    const { pluginDir, cleanup } = (0, plugins_1.resolvePluginSource)(source);
+    try {
+        const manifest = (0, plugins_1.loadPluginManifest)(pluginDir);
+        const { destDir, keyFile } = (0, plugins_1.resolvePluginPaths)(manifest);
+        // Check if already installed (unless --force)
+        const pluginsData = (0, plugins_1.readPluginsFile)(targetDir);
+        const alreadyIndex = pluginsData.plugins.findIndex((p) => p.name === manifest.name);
+        const alreadyInstalled = alreadyIndex !== -1;
+        if (alreadyInstalled && !force) {
+            console.log(`Plugin "${manifest.name}" is already installed. Use --force to reinstall.`);
+            return;
+        }
+        // Build install list
+        const items = (0, plugins_1.buildPluginInstallList)(pluginDir);
+        if (items.length === 0) {
+            console.error(`Error: plugin "${manifest.name}" has no files to install.`);
+            process.exit(1);
+        }
+        if (dryRun) {
+            const action = alreadyInstalled ? 'reinstall' : 'install';
+            console.log(`Devflow: dry run — ${action} plugin "${manifest.name}" into ${targetDir}`);
+            for (const { dest } of items) {
+                const fileExists = (0, install_1.exists)(dest, targetDir);
+                const tag = !fileExists ? '[create]   ' : force ? '[overwrite]' : '[skip]     ';
+                console.log(`  ${tag}  ${dest}`);
+            }
+            console.log('\nDry run complete. Run without --dry-run to apply.');
+            return;
+        }
+        const action = alreadyInstalled ? 'reinstalling' : 'installing';
+        console.log(`Devflow: ${action} plugin "${manifest.name}" into ${targetDir}\n`);
+        for (const item of items) {
+            const existed = (0, install_1.exists)(item.dest, targetDir);
+            // Safety: never overwrite files outside Devflow-managed paths without --force
+            if (existed && !force && !(0, install_1.isManaged)(item.dest)) {
+                console.log(`  –  ${item.dest} (skipped – not Devflow-managed)`);
+                continue;
+            }
+            try {
+                (0, install_1.copyItem)(item, targetDir);
+                const suffix = existed ? ' (overwritten)' : '';
+                console.log(`  ✓  ${item.dest}${suffix}`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`  ✗  ${item.dest}  →  ${msg}`);
+                process.exit(1);
+            }
+        }
+        // Update plugins.yml
+        const entry = {
+            name: manifest.name,
+            source,
+            version: manifest.version,
+            destDir,
+            keyFile,
+        };
+        if (alreadyInstalled) {
+            pluginsData.plugins[alreadyIndex] = entry;
+        }
+        else {
+            pluginsData.plugins.push(entry);
+        }
+        (0, plugins_1.writePluginsFile)(targetDir, pluginsData);
+        console.log(`\nPlugin "${manifest.name}" installed. Recorded in .devflow/plugins.yml`);
+    }
+    finally {
+        cleanup?.();
+    }
+}
+function runRemove(name, options) {
+    const targetDir = (0, install_1.resolveTarget)(options.target ?? process.cwd());
+    const pluginsData = (0, plugins_1.readPluginsFile)(targetDir);
+    const index = pluginsData.plugins.findIndex((p) => p.name === name);
+    if (index === -1) {
+        console.error(`Error: plugin "${name}" is not recorded in .devflow/plugins.yml`);
+        process.exit(1);
+    }
+    const plugin = pluginsData.plugins[index];
+    const pluginDestDir = path.join(targetDir, plugin.destDir);
+    if (fs.existsSync(pluginDestDir)) {
+        fs.rmSync(pluginDestDir, { recursive: true, force: true });
+        console.log(`Removed: ${plugin.destDir}`);
+    }
+    else {
+        console.log(`Note: ${plugin.destDir} was not found on disk (already removed)`);
+    }
+    pluginsData.plugins.splice(index, 1);
+    (0, plugins_1.writePluginsFile)(targetDir, pluginsData);
+    console.log(`Plugin "${name}" removed from .devflow/plugins.yml`);
+}