@rse/ase 0.0.5 → 0.0.7

package/README.md

@@ -1,7 +1,7 @@
 
 $ npx @rse/ase init
-$ npx @rse/ase config agent.dev.llm.type=anthropic-claude-sonnet-4.5
-$ npx @rse/ase config agent.dev.llm.key=<foo>
+$ npx @rse/ase config agent.dev.llm.type anthropic-claude-sonnet-4.5
+$ npx @rse/ase config agent.dev.llm.key <foo>
 $ npx @rse/ase agent dev start
 
 Agents

package/dst/ase-agent-base.js

@@ -7,37 +7,28 @@
 export const createAgentCommandModule = (category, description, subCommands) => {
     /*  create sub-command handler  */
     const createSubCommandHandler = (subCommand) => {
-        return (argv) => {
-            if (argv.debug)
+        return (_opts, cmd) => {
+            const opts = cmd.optsWithGlobals();
+            if (opts.debug)
                 console.log(`DEBUG: agent ${category} ${subCommand} command`);
-            if (argv.verbose)
+            if (opts.verbose)
                 console.log(`VERBOSE: executing agent ${category} ${subCommand}...`);
             console.log(`Executing agent ${category} ${subCommand}...`);
             /*  TODO: implement agent ${category} sub-command logic  */
         };
     };
-    return {
-        command: `${category} <subcommand>`,
-        describe: `Execute ${description} agent operations`,
-        builder: (yargs) => {
-            let builder = yargs
-                .option("verbose", {
-                alias: "v",
-                type: "boolean",
-                describe: "Enable verbose output",
-                default: false
-            })
-                .demandCommand(1, `You need to specify a ${category} subcommand`);
-            /*  register all sub-commands  */
-            for (const subCmd of subCommands) {
-                builder = builder.command(subCmd, `Execute agent ${category} ${subCmd} operation`, () => { }, createSubCommandHandler(subCmd));
-            }
-            return builder;
-        },
-        handler: (argv) => {
-            /*  this handler is not called when sub-commands are used  */
-            if (argv.debug)
-                console.log(`DEBUG: agent ${category} command (no subcommand)`);
+    return (parent) => {
+        const agent = parent
+            .command(`${category}`)
+            .description(`Execute ${description} agent operations`)
+            .option("-v, --verbose", "Enable verbose output", false);
+        /*  register all sub-commands  */
+        for (const subCmd of subCommands) {
+            agent
+                .command(subCmd)
+                .description(`Execute agent ${category} ${subCmd} operation`)
+                .action(createSubCommandHandler(subCmd));
         }
+        return agent;
     };
 };

package/dst/ase-agent-biz.js

@@ -12,38 +12,29 @@ const bizSubCommands = [
 ];
 /*  create sub-command handler  */
 const createSubCommandHandler = (subCommand) => {
-    return (argv) => {
-        if (argv.debug)
+    return (_opts, cmd) => {
+        const opts = cmd.optsWithGlobals();
+        if (opts.debug)
             console.log(`DEBUG: agent biz ${subCommand} command`);
-        if (argv.verbose)
+        if (opts.verbose)
             console.log(`VERBOSE: executing agent biz ${subCommand}...`);
         console.log(`Executing agent biz ${subCommand}...`);
         /*  TODO: implement agent biz sub-command logic  */
     };
 };
-/*  create and export biz command module  */
-const bizCommand = {
-    command: "biz <subcommand>",
-    describe: "Execute business agent operations",
-    builder: (yargs) => {
-        let builder = yargs
-            .option("verbose", {
-            alias: "v",
-            type: "boolean",
-            describe: "Enable verbose output",
-            default: false
-        })
-            .demandCommand(1, "You need to specify a biz subcommand");
-        /*  register all sub-commands  */
-        for (const subCmd of bizSubCommands) {
-            builder = builder.command(subCmd, `Execute agent biz ${subCmd} operation`, () => { }, createSubCommandHandler(subCmd));
-        }
-        return builder;
-    },
-    handler: (argv) => {
-        /*  this handler is not called when sub-commands are used  */
-        if (argv.debug)
-            console.log("DEBUG: agent biz command (no subcommand)");
+/*  register biz command on the given parent  */
+const registerBizCommand = (parent) => {
+    const biz = parent
+        .command("biz")
+        .description("Execute business agent operations")
+        .option("-v, --verbose", "Enable verbose output", false);
+    /*  register all sub-commands  */
+    for (const subCmd of bizSubCommands) {
+        biz
+            .command(subCmd)
+            .description(`Execute agent biz ${subCmd} operation`)
+            .action(createSubCommandHandler(subCmd));
     }
+    return biz;
 };
-export default bizCommand;
+export default registerBizCommand;

package/dst/ase-agent-dev.js

@@ -12,38 +12,29 @@ const devSubCommands = [
 ];
 /*  create sub-command handler  */
 const createSubCommandHandler = (subCommand) => {
-    return (argv) => {
-        if (argv.debug)
+    return (_opts, cmd) => {
+        const opts = cmd.optsWithGlobals();
+        if (opts.debug)
             console.log(`DEBUG: agent dev ${subCommand} command`);
-        if (argv.verbose)
+        if (opts.verbose)
             console.log(`VERBOSE: executing agent dev ${subCommand}...`);
         console.log(`Executing agent dev ${subCommand}...`);
         /*  TODO: implement agent dev sub-command logic  */
     };
 };
-/*  create and export dev command module  */
-const devCommand = {
-    command: "dev <subcommand>",
-    describe: "Execute development agent operations",
-    builder: (yargs) => {
-        let builder = yargs
-            .option("verbose", {
-            alias: "v",
-            type: "boolean",
-            describe: "Enable verbose output",
-            default: false
-        })
-            .demandCommand(1, "You need to specify a dev subcommand");
-        /*  register all sub-commands  */
-        for (const subCmd of devSubCommands) {
-            builder = builder.command(subCmd, `Execute agent dev ${subCmd} operation`, () => { }, createSubCommandHandler(subCmd));
-        }
-        return builder;
-    },
-    handler: (argv) => {
-        /*  this handler is not called when sub-commands are used  */
-        if (argv.debug)
-            console.log("DEBUG: agent dev command (no subcommand)");
+/*  register dev command on the given parent  */
+const registerDevCommand = (parent) => {
+    const dev = parent
+        .command("dev")
+        .description("Execute development agent operations")
+        .option("-v, --verbose", "Enable verbose output", false);
+    /*  register all sub-commands  */
+    for (const subCmd of devSubCommands) {
+        dev
+            .command(subCmd)
+            .description(`Execute agent dev ${subCmd} operation`)
+            .action(createSubCommandHandler(subCmd));
     }
+    return dev;
 };
-export default devCommand;
+export default registerDevCommand;

package/dst/ase-agent-ops.js

@@ -12,38 +12,29 @@ const opsSubCommands = [
 ];
 /*  create sub-command handler  */
 const createSubCommandHandler = (subCommand) => {
-    return (argv) => {
-        if (argv.debug)
+    return (_opts, cmd) => {
+        const opts = cmd.optsWithGlobals();
+        if (opts.debug)
             console.log(`DEBUG: agent ops ${subCommand} command`);
-        if (argv.verbose)
+        if (opts.verbose)
             console.log(`VERBOSE: executing agent ops ${subCommand}...`);
         console.log(`Executing agent ops ${subCommand}...`);
         /*  TODO: implement agent ops sub-command logic  */
     };
 };
-/*  create and export ops command module  */
-const opsCommand = {
-    command: "ops <subcommand>",
-    describe: "Execute operations agent operations",
-    builder: (yargs) => {
-        let builder = yargs
-            .option("verbose", {
-            alias: "v",
-            type: "boolean",
-            describe: "Enable verbose output",
-            default: false
-        })
-            .demandCommand(1, "You need to specify an ops subcommand");
-        /*  register all sub-commands  */
-        for (const subCmd of opsSubCommands) {
-            builder = builder.command(subCmd, `Execute agent ops ${subCmd} operation`, () => { }, createSubCommandHandler(subCmd));
-        }
-        return builder;
-    },
-    handler: (argv) => {
-        /*  this handler is not called when sub-commands are used  */
-        if (argv.debug)
-            console.log("DEBUG: agent ops command (no subcommand)");
+/*  register ops command on the given parent  */
+const registerOpsCommand = (parent) => {
+    const ops = parent
+        .command("ops")
+        .description("Execute operations agent operations")
+        .option("-v, --verbose", "Enable verbose output", false);
+    /*  register all sub-commands  */
+    for (const subCmd of opsSubCommands) {
+        ops
+            .command(subCmd)
+            .description(`Execute agent ops ${subCmd} operation`)
+            .action(createSubCommandHandler(subCmd));
     }
+    return ops;
 };
-export default opsCommand;
+export default registerOpsCommand;

package/dst/ase-agent-prd.js

@@ -12,38 +12,29 @@ const prdSubCommands = [
 ];
 /*  create sub-command handler  */
 const createSubCommandHandler = (subCommand) => {
-    return (argv) => {
-        if (argv.debug)
+    return (_opts, cmd) => {
+        const opts = cmd.optsWithGlobals();
+        if (opts.debug)
             console.log(`DEBUG: agent prd ${subCommand} command`);
-        if (argv.verbose)
+        if (opts.verbose)
             console.log(`VERBOSE: executing agent prd ${subCommand}...`);
         console.log(`Executing agent prd ${subCommand}...`);
         /*  TODO: implement agent prd sub-command logic  */
     };
 };
-/*  create and export prd command module  */
-const prdCommand = {
-    command: "prd <subcommand>",
-    describe: "Execute production agent operations",
-    builder: (yargs) => {
-        let builder = yargs
-            .option("verbose", {
-            alias: "v",
-            type: "boolean",
-            describe: "Enable verbose output",
-            default: false
-        })
-            .demandCommand(1, "You need to specify a prd subcommand");
-        /*  register all sub-commands  */
-        for (const subCmd of prdSubCommands) {
-            builder = builder.command(subCmd, `Execute agent prd ${subCmd} operation`, () => { }, createSubCommandHandler(subCmd));
-        }
-        return builder;
-    },
-    handler: (argv) => {
-        /*  this handler is not called when sub-commands are used  */
-        if (argv.debug)
-            console.log("DEBUG: agent prd command (no subcommand)");
+/*  register prd command on the given parent  */
+const registerPrdCommand = (parent) => {
+    const prd = parent
+        .command("prd")
+        .description("Execute production agent operations")
+        .option("-v, --verbose", "Enable verbose output", false);
+    /*  register all sub-commands  */
+    for (const subCmd of prdSubCommands) {
+        prd
+            .command(subCmd)
+            .description(`Execute agent prd ${subCmd} operation`)
+            .action(createSubCommandHandler(subCmd));
     }
+    return prd;
 };
-export default prdCommand;
+export default registerPrdCommand;

package/dst/ase-agent-prj.js

@@ -12,38 +12,29 @@ const prjSubCommands = [
 ];
 /*  create sub-command handler  */
 const createSubCommandHandler = (subCommand) => {
-    return (argv) => {
-        if (argv.debug)
+    return (_opts, cmd) => {
+        const opts = cmd.optsWithGlobals();
+        if (opts.debug)
             console.log(`DEBUG: agent prj ${subCommand} command`);
-        if (argv.verbose)
+        if (opts.verbose)
             console.log(`VERBOSE: executing agent prj ${subCommand}...`);
         console.log(`Executing agent prj ${subCommand}...`);
         /*  TODO: implement agent prj sub-command logic  */
     };
 };
-/*  create and export prj command module  */
-const prjCommand = {
-    command: "prj <subcommand>",
-    describe: "Execute project agent operations",
-    builder: (yargs) => {
-        let builder = yargs
-            .option("verbose", {
-            alias: "v",
-            type: "boolean",
-            describe: "Enable verbose output",
-            default: false
-        })
-            .demandCommand(1, "You need to specify a prj subcommand");
-        /*  register all sub-commands  */
-        for (const subCmd of prjSubCommands) {
-            builder = builder.command(subCmd, `Execute agent prj ${subCmd} operation`, () => { }, createSubCommandHandler(subCmd));
-        }
-        return builder;
-    },
-    handler: (argv) => {
-        /*  this handler is not called when sub-commands are used  */
-        if (argv.debug)
-            console.log("DEBUG: agent prj command (no subcommand)");
+/*  register prj command on the given parent  */
+const registerPrjCommand = (parent) => {
+    const prj = parent
+        .command("prj")
+        .description("Execute project agent operations")
+        .option("-v, --verbose", "Enable verbose output", false);
+    /*  register all sub-commands  */
+    for (const subCmd of prjSubCommands) {
+        prj
+            .command(subCmd)
+            .description(`Execute agent prj ${subCmd} operation`)
+            .action(createSubCommandHandler(subCmd));
     }
+    return prj;
 };
-export default prjCommand;
+export default registerPrjCommand;

package/dst/ase-agent.js

@@ -3,33 +3,23 @@
 **  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
-import bizCommand from "./ase-agent-biz.js";
-import devCommand from "./ase-agent-dev.js";
-import opsCommand from "./ase-agent-ops.js";
-import prdCommand from "./ase-agent-prd.js";
-import prjCommand from "./ase-agent-prj.js";
-const agentCommand = {
-    command: "agent <subcommand>",
-    describe: "Execute agent operations",
-    builder: (yargs) => {
-        return yargs
-            .option("verbose", {
-            alias: "v",
-            type: "boolean",
-            describe: "Enable verbose output",
-            default: false
-        })
-            .command(bizCommand)
-            .command(devCommand)
-            .command(opsCommand)
-            .command(prdCommand)
-            .command(prjCommand)
-            .demandCommand(1, "You need to specify an agent subcommand");
-    },
-    handler: (argv) => {
-        /*  this handler is not called when sub-commands are used  */
-        if (argv.debug)
-            console.log("DEBUG: agent command (no subcommand)");
-    }
+import registerBizCommand from "./ase-agent-biz.js";
+import registerDevCommand from "./ase-agent-dev.js";
+import registerOpsCommand from "./ase-agent-ops.js";
+import registerPrdCommand from "./ase-agent-prd.js";
+import registerPrjCommand from "./ase-agent-prj.js";
+/*  register agent command on the given program  */
+const registerAgentCommand = (program) => {
+    const agent = program
+        .command("agent")
+        .description("Execute agent operations")
+        .option("-v, --verbose", "Enable verbose output", false);
+    /*  register all agent sub-commands  */
+    registerBizCommand(agent);
+    registerDevCommand(agent);
+    registerOpsCommand(agent);
+    registerPrdCommand(agent);
+    registerPrjCommand(agent);
+    return agent;
 };
-export default agentCommand;
+export default registerAgentCommand;

package/dst/ase-config.js

@@ -3,34 +3,186 @@
 **  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
-const configCommand = {
-    command: "config [assignment]",
-    describe: "Manage ASE configuration",
-    builder: (yargs) => {
-        return yargs
-            .positional("assignment", {
-            type: "string",
-            describe: "Configuration assignment (key=value) or key to query"
-        });
-    },
-    handler: (argv) => {
-        if (argv.debug)
-            console.log("DEBUG: config command", argv);
-        const assignment = argv.assignment;
-        if (!assignment) {
-            console.log("Listing all configuration...");
-            /*  TODO: implement configuration listing logic  */
+import path from "node:path";
+import fs from "node:fs";
+import { Document, parseDocument, isMap, isScalar } from "yaml";
+import { execaSync } from "execa";
+import * as v from "valibot";
+import Table from "cli-table3";
+/*  schema for ".ase/config.yaml"  */
+export const configSchema = v.nullish(v.strictObject({
+    project: v.optional(v.strictObject({
+        id: v.optional(v.pipe(v.string(), v.minLength(1)))
+    }))
+}));
+/*  encapsulate read/write access to a project-local ".ase/<name>.yaml" file  */
+export class Config {
+    filename;
+    doc;
+    schema;
+    constructor(name, schema) {
+        const rel = path.join(".ase", `${name}.yaml`);
+        const found = this.findUpward(process.cwd(), rel);
+        this.filename = found ?? path.join(this.gitToplevel() ?? process.cwd(), rel);
+        this.doc = new Document();
+        this.schema = schema ?? null;
+    }
+    /*  upward-walk on filesystem for a file path relative to a start directory  */
+    findUpward(start, rel) {
+        let dir = start;
+        for (;;) {
+            const candidate = path.join(dir, rel);
+            if (fs.existsSync(candidate))
+                return candidate;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+    }
+    /*  determine the Git top-level directory, if inside a Git repository  */
+    gitToplevel() {
+        try {
+            const result = execaSync("git", ["rev-parse", "--show-toplevel"], {
+                stderr: "ignore"
+            });
+            return result.stdout.trim() || null;
         }
-        else if (assignment.includes("=")) {
-            const [key, ...valueParts] = assignment.split("=");
-            const value = valueParts.join("=");
-            console.log(`Setting configuration: ${key} = ${value}`);
-            /*  TODO: implement configuration storage logic  */
+        catch {
+            return null;
+        }
+    }
+    /*  read configuration file into memory  */
+    read() {
+        const text = fs.existsSync(this.filename) ? fs.readFileSync(this.filename, "utf8") : "";
+        this.doc = parseDocument(text);
+        this.validate("lenient");
+    }
+    /*  write in-memory configuration back to file  */
+    write() {
+        this.validate("strict");
+        fs.mkdirSync(path.dirname(this.filename), { recursive: true });
+        fs.writeFileSync(this.filename, this.doc.toString({ indent: 4 }), "utf8");
+    }
+    /*  validate in-memory configuration against the optional schema  */
+    validate(mode = "strict") {
+        if (this.schema === null)
+            return;
+        for (;;) {
+            const result = v.safeParse(this.schema, this.doc.toJS());
+            if (result.success)
+                return;
+            if (mode === "strict") {
+                const issues = result.issues.map((i) => {
+                    const dotPath = (i.path ?? []).map((p) => String(p.key)).join(".");
+                    return dotPath ? `${dotPath}: ${i.message}` : i.message;
+                }).join("; ");
+                throw new Error(`invalid configuration in ${this.filename}: ${issues}`);
+            }
+            let progressed = false;
+            for (const i of result.issues) {
+                const segs = (i.path ?? []).map((p) => String(p.key));
+                const dotPath = segs.join(".");
+                process.stderr.write(`ase: warning: invalid entry in ${this.filename}: ${dotPath ? `${dotPath}: ` : ""}${i.message}\n`);
+                if (segs.length > 0) {
+                    this.doc.deleteIn(segs);
+                    progressed = true;
+                }
+            }
+            if (!progressed)
+                return;
         }
-        else {
-            console.log(`Getting configuration: ${assignment}`);
-            /*  TODO: implement configuration retrieval logic  */
+    }
+    /*  retrieve a value at a dotted key, or the root contents if no key given  */
+    get(key) {
+        if (key === undefined)
+            return this.doc.contents;
+        return this.doc.getIn(key.split("."));
+    }
+    /*  set a value at a dotted key, creating intermediate maps as needed  */
+    set(key, value) {
+        const segments = key.split(".");
+        for (let i = 1; i < segments.length; i++) {
+            const prefix = segments.slice(0, i);
+            const node = this.doc.getIn(prefix, true);
+            if (!isMap(node))
+                this.doc.setIn(prefix, this.doc.createNode({}));
         }
+        this.doc.setIn(segments, value);
+        this.validate("strict");
+    }
+    /*  delete a value at a dotted key  */
+    delete(key) {
+        this.doc.deleteIn(key.split("."));
     }
+}
+/*  register CLI command "ase config"  */
+const registerConfigCommand = (program) => {
+    const configCmd = program
+        .command("config")
+        .description("Manage ASE configuration")
+        .action((_opts, cmd) => {
+        cmd.help();
+    });
+    /*  register CLI sub-command "ase config get"  */
+    configCmd
+        .command("get")
+        .description("Print the value at a dotted configuration key")
+        .argument("<key>", "Configuration key (dotted path)")
+        .action((key) => {
+        const cfg = new Config("config", configSchema);
+        cfg.read();
+        const v = cfg.get(key);
+        if (isMap(v))
+            throw new Error(`key "${key}" is not a leaf key`);
+        console.log(isScalar(v) ? v.value : v);
+    });
+    /*  register CLI sub-command "ase config set"  */
+    configCmd
+        .command("set")
+        .description("Set the value at a dotted configuration key")
+        .argument("<key>", "Configuration key (dotted path)")
+        .argument("<value>", "Configuration value")
+        .action((key, value) => {
+        const cfg = new Config("config", configSchema);
+        cfg.read();
+        console.log(`${key}: ${value}`);
+        cfg.set(key, value);
+        cfg.write();
+    });
+    /*  register CLI sub-command "ase config list"  */
+    configCmd
+        .command("list")
+        .description("List all configured values as flat dotted keys")
+        .action(() => {
+        const cfg = new Config("config", configSchema);
+        cfg.read();
+        const table = new Table({ head: ["key", "value"] });
+        const list = (node, prefix) => {
+            if (isMap(node))
+                for (const item of node.items) {
+                    const k = prefix ? `${prefix}.${item.key}` : String(item.key);
+                    if (isMap(item.value))
+                        list(item.value, k);
+                    else
+                        table.push([k, String(isScalar(item.value) ? item.value.value : item.value)]);
+                }
+        };
+        list(cfg.get(), "");
+        console.log(table.toString());
+    });
+    /*  register CLI sub-command "ase config edit"  */
+    configCmd
+        .command("edit")
+        .description("Edit configuration file with $EDITOR")
+        .action(() => {
+        const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
+        const cfg = new Config("config", configSchema);
+        fs.mkdirSync(path.dirname(cfg.filename), { recursive: true });
+        if (!fs.existsSync(cfg.filename))
+            fs.writeFileSync(cfg.filename, "", "utf8");
+        execaSync(editor, [cfg.filename], { stdio: "inherit" });
+        cfg.read();
+    });
 };
-export default configCommand;
+export default registerConfigCommand;

package/dst/ase-meta-plan.js

@@ -0,0 +1,78 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+import path from "node:path";
+import fs from "node:fs";
+import { execa } from "execa";
+import { mkdirp } from "mkdirp";
+const configCommand = {
+    command: "meta-plan <subcommand>",
+    describe: "Manage plans",
+    builder: (yargs) => {
+        return yargs
+            .command({
+            command: "init",
+            describe: "ensure plan directory exists",
+            handler: async () => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.plan/`;
+                if (!fs.existsSync(planDir))
+                    await mkdirp(planDir);
+            }
+        })
+            .command({
+            command: "load <id>",
+            describe: "load a plan",
+            builder: (yargs) => yargs.positional("id", {
+                type: "string",
+                describe: "plan identifier"
+            }),
+            handler: async (argv) => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.plan/`;
+                const planFile = path.join(planDir, `${argv.id}.md`);
+                const text = fs.existsSync(planFile) ? fs.readFileSync(planFile, "utf8") : "";
+                process.stdout.write(text);
+            }
+        })
+            .command({
+            command: "save <id>",
+            describe: "save a plan",
+            builder: (yargs) => yargs.positional("id", {
+                type: "string",
+                describe: "plan identifier"
+            }),
+            handler: async (argv) => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.plan/`;
+                if (!fs.existsSync(planDir))
+                    await mkdirp(planDir);
+                const planFile = path.join(planDir, `${argv.id}.md`);
+                const text = fs.readFileSync(0, "utf8");
+                fs.writeFileSync(planFile, text);
+            }
+        })
+            .command({
+            command: "edit <id>",
+            describe: "edit a plan interactively with $EDITOR",
+            builder: (yargs) => yargs.positional("id", {
+                type: "string",
+                describe: "plan identifier"
+            }),
+            handler: async (argv) => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.plan/`;
+                const planFile = path.join(planDir, `${argv.id}.md`);
+                if (!fs.existsSync(planDir))
+                    await mkdirp(planDir);
+                const editor = process.env.EDITOR ?? "vi";
+                await execa(editor, [planFile], { stdio: "inherit" });
+            }
+        })
+            .demandCommand(1, "You need to specify a sub-command");
+    },
+    handler: () => { }
+};
+export default configCommand;

package/dst/ase-plan.js

@@ -0,0 +1,82 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+import path from "node:path";
+import fs from "node:fs";
+import { execa } from "execa";
+import { mkdirp } from "mkdirp";
+const planCommand = {
+    command: "plan <subcommand>",
+    describe: "Manage plans",
+    builder: (yargs) => {
+        return yargs
+            .command({
+            command: "ensure",
+            describe: "ensure plan directory exists",
+            handler: async () => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.ase/plan/`;
+                if (!fs.existsSync(planDir))
+                    await mkdirp(planDir);
+                process.stdout.write(planDir);
+            }
+        })
+            .command({
+            command: "load <id>",
+            describe: "load a plan",
+            builder: (yargs) => yargs.positional("id", {
+                type: "string",
+                describe: "plan identifier"
+            }),
+            handler: async (argv) => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.ase/plan/`;
+                const planFile = path.join(planDir, `${argv.id}.md`);
+                const text = fs.existsSync(planFile) ? fs.readFileSync(planFile, "utf8") : "";
+                process.stdout.write(text);
+            }
+        })
+            .command({
+            command: "save <id>",
+            describe: "save a plan",
+            builder: (yargs) => yargs.positional("id", {
+                type: "string",
+                describe: "plan identifier"
+            }),
+            handler: async (argv) => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.ase/plan/`;
+                if (!fs.existsSync(planDir))
+                    await mkdirp(planDir);
+                const planFile = path.join(planDir, `${argv.id}.md`);
+                const chunks = [];
+                for await (const chunk of process.stdin)
+                    chunks.push(chunk);
+                const text = Buffer.concat(chunks).toString("utf8");
+                fs.writeFileSync(planFile, text);
+            }
+        })
+            .command({
+            command: "edit <id>",
+            describe: "edit a plan interactively with $EDITOR",
+            builder: (yargs) => yargs.positional("id", {
+                type: "string",
+                describe: "plan identifier"
+            }),
+            handler: async (argv) => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.ase/plan/`;
+                const planFile = path.join(planDir, `${argv.id}.md`);
+                if (!fs.existsSync(planDir))
+                    await mkdirp(planDir);
+                const editor = process.env.EDITOR ?? "vi";
+                await execa(editor, [planFile], { stdio: "inherit" });
+            }
+        })
+            .demandCommand(1, "You need to specify a sub-command");
+    },
+    handler: () => { }
+};
+export default planCommand;

package/dst/ase-service.js

@@ -0,0 +1,302 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+import path from "node:path";
+import fs from "node:fs";
+import net from "node:net";
+import { spawn } from "node:child_process";
+import Hapi from "@hapi/hapi";
+import axios from "axios";
+import * as v from "valibot";
+import { Config, configSchema } from "./ase-config.js";
+const SERVE_ENV = "ASE_SERVICE_SERVE";
+const HOST = "127.0.0.1";
+const IDLE_MS = 30 * 60 * 1000;
+const TICK_MS = 60 * 1000;
+const PORT_MIN = 42000;
+const PORT_MAX = 44000;
+const PORT_TRIES = 20;
+/*  schema for ".ase/service.yaml"  */
+const serviceSchema = v.nullish(v.strictObject({
+    port: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1024), v.maxValue(65535)))
+}));
+/*  load optional ".ase/config.yaml" and ".ase/service.yaml" files  */
+const loadContext = () => {
+    /*  load files  */
+    const cfg = new Config("config", configSchema);
+    cfg.read();
+    const svc = new Config("service", serviceSchema);
+    svc.read();
+    /*  determine project id  */
+    const rawId = cfg.get("project.id");
+    const projectId = (rawId === undefined || rawId === null) ? path.basename(process.cwd()) : rawId;
+    /*  determine service port  */
+    const rawPort = svc.get("port");
+    const port = (rawPort === undefined || rawPort === null) ? null : rawPort;
+    /*  determine path to ".ase" directory  */
+    const aseDir = path.dirname(svc.filename);
+    /*  return context information  */
+    return {
+        projectId,
+        port,
+        svc,
+        aseDir
+    };
+};
+/*  try binding a single candidate port to verify availability  */
+const tryBind = (port) => {
+    return new Promise((resolve) => {
+        const s = net.createServer();
+        s.once("error", () => {
+            resolve(false);
+        });
+        s.once("listening", () => {
+            s.close(() => resolve(true));
+        });
+        s.listen(port, HOST);
+    });
+};
+/*  allocate a fresh random port in PORT_MIN..PORT_MAX  */
+const allocatePort = async () => {
+    for (let i = 0; i < PORT_TRIES; i++) {
+        const p = PORT_MIN + Math.floor(Math.random() * (PORT_MAX - PORT_MIN + 1));
+        if (await tryBind(p))
+            return p;
+    }
+    throw new Error(`failed to allocate a port in ${PORT_MIN}..${PORT_MAX} after ${PORT_TRIES} attempts`);
+};
+/*  persist an allocated port into ".ase/service.yaml"  */
+const persistPort = (svc, port) => {
+    svc.set("port", port);
+    svc.write();
+};
+/*  distinguish ECONNREFUSED from other Axios transport errors  */
+const isConnRefused = (err) => {
+    const e = err;
+    return e?.code === "ECONNREFUSED" || e?.cause?.code === "ECONNREFUSED";
+};
+/*  probe the service  */
+const probe = async (port) => {
+    try {
+        const r = await axios.request({
+            method: "OPTIONS",
+            url: `http://${HOST}:${port}/`,
+            timeout: 2000,
+            validateStatus: () => true
+        });
+        return r.status;
+    }
+    catch (err) {
+        if (isConnRefused(err))
+            return null;
+        throw err;
+    }
+};
+/*  service-side: bind HAPI server until "/stop" command is received or idle timeout happens  */
+const runService = async (ctx) => {
+    /*  establish HAPI HTTP/REST service  */
+    const server = Hapi.server({ host: HOST, port: ctx.port });
+    /*  track last activity  */
+    let lastActivity = Date.now();
+    server.ext("onRequest", (_request, h) => {
+        lastActivity = Date.now();
+        return h.continue;
+    });
+    /*  listen to HTTP/REST endpoints  */
+    server.route({
+        method: "OPTIONS",
+        path: "/",
+        handler: (_request, h) => {
+            return h.response().code(204);
+        }
+    });
+    server.route({
+        method: "GET",
+        path: "/stop",
+        handler: (_request, h) => {
+            setImmediate(async () => {
+                await server.stop({ timeout: 1000 });
+                process.exit(0);
+            });
+            return h.response({ ok: true }).code(200);
+        }
+    });
+    server.route({
+        method: "POST",
+        path: "/command",
+        options: { payload: { parse: true, allow: "application/json" } },
+        handler: (request, h) => {
+            const payload = request.payload;
+            if (!payload || typeof payload.command !== "string")
+                return h.response({ error: "missing or invalid 'command' field" }).code(400);
+            if (payload.command === "foo") {
+                return h.response({
+                    ok: true,
+                    projectId: ctx.projectId,
+                    command: "Hello World" // FIXME
+                }).code(200);
+            }
+            else
+                return h.response({ error: "invalid 'command' field" }).code(400);
+        }
+    });
+    /*  start service  */
+    try {
+        await server.start();
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "EADDRINUSE") {
+            /*  race-loser re-probe: another "ase service start" won the race  */
+            const status = await probe(ctx.port).catch(() => null);
+            if (status !== null && status >= 200 && status < 300)
+                process.exit(0);
+            process.stderr.write(`ase: service: port ${ctx.port} in use, but not responding!\n`);
+            process.exit(1);
+        }
+        process.stderr.write(`ase: service: ${e.message}\n`);
+        process.exit(1);
+    }
+    /*  stop service after idle timeout  */
+    setInterval(() => {
+        if (Date.now() - lastActivity > IDLE_MS) {
+            server.stop({ timeout: 1000 }).then(() => {
+                process.exit(0);
+            });
+        }
+    }, TICK_MS).unref();
+};
+/*  spawn the current executable detached as a background service  */
+const spawnDetached = (aseDir) => {
+    fs.mkdirSync(aseDir, { recursive: true });
+    const logFile = path.join(aseDir, "service.log");
+    const log = fs.openSync(logFile, "a");
+    const child = spawn(process.execPath, [process.argv[1], "service", "start"], {
+        detached: true,
+        env: { ...process.env, [SERVE_ENV]: "1" },
+        stdio: ["ignore", log, log]
+    });
+    child.unref();
+};
+/*  start flow: ensure port, probe, optionally detach  */
+const doStart = async () => {
+    const ctx = loadContext();
+    let port = ctx.port;
+    if (port === null) {
+        port = await allocatePort();
+        persistPort(ctx.svc, port);
+    }
+    if (process.env[SERVE_ENV] === "1") {
+        await runService({ ...ctx, port });
+        return await new Promise(() => { });
+    }
+    const status = await probe(port);
+    if (status !== null && status >= 200 && status < 300)
+        return 0;
+    spawnDetached(ctx.aseDir);
+    for (let i = 0; i < 50; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        const s = await probe(port);
+        if (s !== null && s >= 200 && s < 300) {
+            process.stdout.write(`ase: service: started on port ${port}\n`);
+            return 0;
+        }
+    }
+    throw new Error("service failed to start within timeout");
+};
+/*  stop flow: no-op if no port configured or connection refused  */
+const doStop = async () => {
+    const ctx = loadContext();
+    if (ctx.port === null) {
+        process.stdout.write("ase: service: not running (no port configured)\n");
+        return 0;
+    }
+    try {
+        const r = await axios.request({
+            method: "GET",
+            url: `http://${HOST}:${ctx.port}/stop`,
+            timeout: 5000,
+            validateStatus: () => true
+        });
+        return r.status >= 200 && r.status < 300 ? 0 : 1;
+    }
+    catch (err) {
+        if (isConnRefused(err)) {
+            process.stdout.write(`ase: service: not running (port ${ctx.port} not responding)\n`);
+            return 0;
+        }
+        throw err;
+    }
+};
+/*  passthrough flow: POST /command with the arbitrary cmd token  */
+const doPassthrough = async (cmd) => {
+    let ctx = loadContext();
+    if (ctx.port === null) {
+        await doStart();
+        ctx = loadContext();
+        if (ctx.port === null)
+            throw new Error("service not running (no port configured after auto-start)");
+    }
+    const send = async () => {
+        const r = await axios.request({
+            method: "POST",
+            url: `http://${HOST}:${ctx.port}/command`,
+            headers: { "Content-Type": "application/json" },
+            data: { command: cmd },
+            timeout: 0,
+            validateStatus: () => true,
+            responseType: "text",
+            transformResponse: [(x) => x]
+        });
+        const body = typeof r.data === "string" ? r.data : JSON.stringify(r.data);
+        process.stdout.write(body);
+        if (!body.endsWith("\n"))
+            process.stdout.write("\n");
+        return r.status >= 200 && r.status < 300 ? 0 : 1;
+    };
+    try {
+        return await send();
+    }
+    catch (err) {
+        if (isConnRefused(err)) {
+            await doStart();
+            return await send();
+        }
+        throw err;
+    }
+};
+/*  register CLI command "ase service"  */
+const registerServiceCommand = (program) => {
+    const service = program
+        .command("service")
+        .description("Manage per-project background HTTP service")
+        .action(() => {
+        service.outputHelp();
+        process.exit(1);
+    });
+    /*  register CLI sub-command "ase service start"  */
+    service
+        .command("start")
+        .description("Start the background service")
+        .action(async () => {
+        process.exit(await doStart());
+    });
+    /*  register CLI sub-command "ase service stop"  */
+    service
+        .command("stop")
+        .description("Stop the background service")
+        .action(async () => {
+        process.exit(await doStop());
+    });
+    /*  register CLI sub-command "ase service send"  */
+    service
+        .command("send")
+        .description("Send a command to the background service")
+        .argument("<cmd>", "Command token to dispatch to the service")
+        .action(async (cmd) => {
+        process.exit(await doPassthrough(cmd));
+    });
+};
+export default registerServiceCommand;

package/dst/ase-setup.js

@@ -0,0 +1,18 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+const registerSetupCommand = (program) => {
+    program
+        .command("setup")
+        .description("Setup ASE")
+        .action((_opts, cmd) => {
+        const debug = Boolean(cmd.optsWithGlobals().debug);
+        if (debug)
+            console.log("DEBUG: setup command");
+        console.log("Setup ASE...");
+        /*  TODO: implement setup logic  */
+    });
+};
+export default registerSetupCommand;

package/dst/ase.1

@@ -3,23 +3,59 @@
 \fBase\fR - Agentic Software Engineering (ASE)
 .SH "SYNOPSIS"
 .P
-\fBase\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-V\fR|\fB--version\fR\[rB] \[lB]\fIcommand\fR \[lB]\fIoptions\fR \[lB]...\[rB]\[rB]\[rB] \[lB]\fIargs\fR \[lB]...\[rB]\[rB]\[rB]
+\fBase\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-V\fR|\fB--version\fR\[rB] \[lB]\fB-d\fR|\fB--debug\fR\[rB] \[lB]\fIcommand\fR \[lB]\fIoptions\fR \[lB]...\[rB]\[rB] \[lB]\fIargs\fR \[lB]...\[rB]\[rB]\[rB]
 .SH "DESCRIPTION"
 .P
-\fBase\fR, \fIAgentic Software Engineeing (ASE)\fR, is a small command-line tool...
+\fBase\fR, \fIAgentic Software Engineering (ASE)\fR, is the command-line companion tool to the \fIASE\fR Claude Code plugin. It provides project-level configuration management and a small per-project background HTTP service for dispatching commands.
 .SH "OPTIONS"
 .P
-The following command-line options and arguments exist:
+The following top-level command-line options exist:
 .RS 0
 .IP \(bu 4
 \[lB]\fB-h\fR|\fB--help\fR\[rB]: Show program usage information only.
 .IP \(bu 4
 \[lB]\fB-V\fR|\fB--version\fR\[rB]: Show program version information only.
+.IP \(bu 4
+\[lB]\fB-d\fR|\fB--debug\fR\[rB]: Enable debug output. The flag is inherited by all subcommands and can be inspected inside handlers via \fBcmd.optsWithGlobals()\fR.
+.RE 0
+
+.SH "COMMANDS"
+.P
+The following top-level commands exist:
+.RS 0
+.IP \(bu 4
+\fBase config\fR: Manage \fIASE\fR configuration stored in \fB.ase/config.yaml\fR. Without a subcommand, prints usage information. The file is validated against a schema: on read, unknown or invalid entries are warned about and silently dropped from the in-memory view; on set/write, they cause a fatal error.
+.IP \(bu 4
+\fBase config get\fR \fIkey\fR: Print the value at the given dotted \fIkey\fR. Fails with an error if \fIkey\fR does not resolve to a leaf value.
+.IP \(bu 4
+\fBase config set\fR \fIkey\fR \fIvalue\fR: Set the value at the given dotted \fIkey\fR (creating intermediate maps as needed) and persist the file.
+.IP \(bu 4
+\fBase config list\fR: List all configured values as flat dotted keys, rendered as a two-column table of \fBkey\fR and \fBvalue\fR.
+.IP \(bu 4
+\fBase config edit\fR: Open \fB.ase/config.yaml\fR in the editor defined by the \fB$EDITOR\fR or \fB$VISUAL\fR environment variable (falling back to \fBvi\fR). The file and its parent directory are created if missing. After the editor exits, the file is re-read and schema warnings are reported.
+.IP \(bu 4
+\fBase service\fR: Manage the per-project background HTTP service. The service is bound to \fB127.0.0.1\fR on a port persisted in \fB.ase/service.yaml\fR and stops itself after 30 minutes of idle time. Without a subcommand, the help text is shown.
+.IP \(bu 4
+\fBase service start\fR: Start the background service (detached). Allocates a random port in the range \fB42000\fR..\fB44000\fR if none is persisted yet, writes it to \fB.ase/service.yaml\fR, and probes readiness. Exits silently with status 0 if the service is already running; prints \fBase: service: started on port <port>\fR on a fresh start.
+.IP \(bu 4
+\fBase service stop\fR: Stop the background service via HTTP \fBGET /stop\fR. Exits silently with status 0 on successful stop. If no port is configured or the port is not responding, prints an informational message and exits with status 0.
+.IP \(bu 4
+\fBase service send\fR \fIcmd\fR: Dispatch the \fIcmd\fR token as a passthrough command to the running service via HTTP \fBPOST /command\fR; if the service is not running, it is auto-started first.
+.RE 0
+
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB.ase/config.yaml\fR: Per-project \fIASE\fR configuration. Read upward from the current working directory. Recognized key: \fBproject.id\fR (non-empty string).
+.IP \(bu 4
+\fB.ase/service.yaml\fR: Per-project service state. Recognized key: \fBport\fR (integer in \fB1024\fR..\fB65535\fR).
+.IP \(bu 4
+\fB.ase/service.log\fR: Stdout/stderr log of the detached background service.
 .RE 0
 
 .SH "HISTORY"
 .P
-\fBase\fR was started to be developed in October 2025...
+\fBase\fR was started to be developed in October 2025.
 .SH "AUTHOR"
 .P
 Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/ase.js

@@ -4,26 +4,36 @@
 **  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
-import yargs from "yargs";
-import { hideBin } from "yargs/helpers";
-import initCommand from "./ase-init.js";
-import configCommand from "./ase-config.js";
-import agentCommand from "./ase-agent.js";
+import { Command, CommanderError } from "commander";
+import registerConfigCommand from "./ase-config.js";
+import registerServiceCommand from "./ase-service.js";
 /*  parse CLI arguments  */
-yargs(hideBin(process.argv))
-    .scriptName("ase")
-    .usage("Usage: $0 <command> [options]")
-    .option("debug", {
-    alias: "d",
-    type: "boolean",
-    describe: "Enable debug output",
-    default: false
-})
-    .command(initCommand)
-    .command(configCommand)
-    .command(agentCommand)
-    .demandCommand(1, "You need to specify a command")
-    .help()
-    .version()
-    .strict()
-    .parse();
+try {
+    /*  establish top-level program  */
+    const program = new Command();
+    program
+        .name("ase")
+        .usage("<command> [options]")
+        .option("-d, --debug", "enable debug output", false)
+        .showHelpAfterError()
+        .enablePositionalOptions()
+        .exitOverride();
+    /*  register top-level commands  */
+    registerConfigCommand(program);
+    registerServiceCommand(program);
+    /*  parse program arguments  */
+    await program.parseAsync(process.argv);
+    /*  gracefully terminate  */
+    process.exit(0);
+}
+catch (err) {
+    if (err instanceof CommanderError) {
+        if (err.exitCode !== 0)
+            process.exit(err.exitCode);
+        else
+            process.exit(0);
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`ase: ERROR: ${message}\n`);
+    process.exit(1);
+}

package/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.0.5",
+    "version":                              "0.0.7",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -18,27 +18,33 @@
     "devDependencies": {
         "eslint":                           "9.39.4",
         "@eslint/js":                       "9.39.4",
-        "@typescript-eslint/parser":        "8.58.0",
-        "@typescript-eslint/eslint-plugin": "8.58.0",
+        "@typescript-eslint/parser":        "8.58.2",
+        "@typescript-eslint/eslint-plugin": "8.58.2",
         "eslint-plugin-n":                  "17.24.0",
         "eslint-plugin-promise":            "7.2.1",
         "eslint-plugin-import":             "2.32.0",
         "neostandard":                      "0.13.0",
-        "globals":                          "17.4.0",
-        "typescript":                       "6.0.2",
+        "globals":                          "17.5.0",
+        "typescript":                       "6.0.3",
 
-        "@rse/stx":                         "1.1.4",
+        "@rse/stx":                         "1.1.5",
         "nodemon":                          "3.1.14",
         "shx":                              "0.4.0",
         "remark-cli":                       "12.0.1",
         "remark":                           "15.0.1",
         "remark-man":                       "9.0.0",
 
-        "@types/node":                      "25.5.2",
-        "@types/yargs":                     "17.0.35"
+        "@types/node":                      "25.6.0"
     },
     "dependencies": {
-        "yargs":                            "18.0.0"
+        "commander":                        "14.0.3",
+        "yaml":                             "2.8.3",
+        "valibot":                          "1.3.1",
+        "execa":                            "9.6.1",
+        "mkdirp":                           "3.0.1",
+        "@hapi/hapi":                       "21.4.8",
+        "axios":                            "1.15.0",
+        "cli-table3":                       "0.6.5"
     },
     "engines": {
         "npm":                              ">=10.0.0",