@agentic-kit/cli 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+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,138 @@
+# @agentic-kit/cli
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+`agent` — a local, secure-by-default coding agent that builds your frontend and your backend. Skills, a backend harness, and offline-capable skill releases, batteries included.
+
+```bash
+npm install -g @agentic-kit/cli
+agent                 # interactive TUI session in the current project
+agent -p "explain this repo"   # one-shot print mode
+```
+
+## What it does
+
+On startup, `agent` assembles the harness skill tree and drops you into an interactive terminal session:
+
+1. **Base layer** — a pinned release of [`constructive-io/constructive-skills`](https://github.com/constructive-io/constructive-skills), fetched as a git tag/branch/SHA tarball into `~/.constructive/data/skills/<version>/` (offline fallback: newest cached release).
+2. **Local overlay** — `~/.constructive/config/skills-overlay/<skill-name>/SKILL.md` (agentskills.io layout), highest precedence: a same-name skill replaces the base skill wholesale.
+3. **Typed db tools** — the [`@agentic-kit/pi`](https://www.npmjs.com/package/@agentic-kit/pi) extension (provision_database, provision_blueprint, describe_schema, add_records, run_codegen, … with confirm gating on pi's built-in y/n dialog) is materialized into the agent dir and loaded by pi automatically.
+
+The merged tree is materialized into the appstash-owned agent dir, so the session picks the skills up natively. All harness state lives in the [appstash](https://github.com/constructive-io/appstash) `~/.constructive/` layout; project directories are untouched.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `agent [options...]` | Start an interactive session with the harness skills |
+| `agent -p "prompt"` | One-shot print mode |
+| `agent init` | Configure the skills source (repo + pin) interactively |
+| `agent skills list` | Resolve and list the effective skill set per layer |
+| `agent skills update` | Re-fetch the base release and re-materialize |
+| `agent help` | Usage |
+
+## Configuration
+
+`~/.constructive/config/skills-manifest.json`:
+
+```json
+{
+  "repo": "constructive-io/constructive-skills",
+  "pin": "^1.0.0",
+  "manifest": {
+    "sources": [
+      { "name": "constructive-skills" },
+      { "name": "local-overlay" }
+    ]
+  }
+}
+```
+
+Env overrides: `AGENT_SKILLS_REPO`, `AGENT_SKILLS_PIN`, `AGENT_HOME` (appstash base dir), `GITHUB_TOKEN` (private skills repos).
+
+Db-tool credentials (read per tool call; without them the tools respond "not signed in"):
+`CONSTRUCTIVE_USER_ID`, `CONSTRUCTIVE_ACCESS_TOKEN`, `CONSTRUCTIVE_API_KEY` (optional), `CONSTRUCTIVE_API_ENDPOINT`, `CONSTRUCTIVE_MODULES_ENDPOINT` (default to the local backend).
+
+## Roadmap
+
+- `agent login` — sign in to a Constructive backend and persist credentials in appstash instead of env vars.
+- Harness system-prompt section + templates/prompts materialization, shared with constructive-desktop via a common adapter package.
+
+## Credits
+
+The interactive session is powered by the excellent [pi coding agent](https://github.com/badlogic/pi-mono) — thank you! `agent` layers the Constructive harness (skill releases, overlays, backend tooling) on top.
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/commands.d.ts

@@ -0,0 +1,5 @@
+import { AgentCliConfig } from './config';
+export declare function skillsList(config: AgentCliConfig): Promise<void>;
+export declare function skillsUpdate(config: AgentCliConfig): Promise<void>;
+export declare function init(config: AgentCliConfig, argv: Record<string, unknown>): Promise<void>;
+export declare function usage(): void;

package/commands.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillsList = skillsList;
+exports.skillsUpdate = skillsUpdate;
+exports.init = init;
+exports.usage = usage;
+const inquirerer_1 = require("inquirerer");
+const config_1 = require("./config");
+const skills_1 = require("./skills");
+const log = (msg) => console.log(`[agent] ${msg}`);
+async function skillsList(config) {
+    const resolved = await (0, skills_1.assembleSkills)(config, log);
+    if (resolved.length === 0) {
+        console.log('No skills resolved.');
+        return;
+    }
+    for (const skill of resolved) {
+        console.log(`${skill.name}  [${skill.sourceName}]  ${skill.description}`);
+    }
+}
+async function skillsUpdate(config) {
+    await (0, skills_1.assembleSkills)(config, log);
+}
+async function init(config, argv) {
+    const prompter = new inquirerer_1.Inquirerer({ noTty: !process.stdin.isTTY });
+    const answers = await prompter.prompt(argv, [
+        {
+            type: 'text',
+            name: 'repo',
+            message: 'Skills repository (owner/repo)',
+            default: config.skillsRepo
+        },
+        {
+            type: 'text',
+            name: 'pin',
+            message: 'Skills pin (tag, semver range, SHA, or branch)',
+            default: config.skillsPin
+        }
+    ]);
+    (0, config_1.saveManifestFile)(config, {
+        repo: answers.repo,
+        pin: answers.pin,
+        manifest: (0, config_1.defaultManifest)()
+    });
+    log(`wrote ${config.manifestFile}`);
+    log(`local overlay dir (highest precedence): ${config.overlayDir}`);
+}
+function usage() {
+    console.log(`agent — the pi coding agent with the Constructive harness baked in
+
+Usage:
+  agent [pi options...]        start an interactive session (pi TUI)
+  agent -p "prompt"            one-shot print mode (pi)
+  agent init                   configure the skills source (repo + pin)
+  agent skills list            resolve + list the effective skill set
+  agent skills update          re-fetch the base release and re-materialize
+  agent help                   show this help
+
+Skills layering (later wins by skill name, wholesale):
+  1. ${'constructive-skills'} release (git tag/branch/SHA pin, offline fallback)
+  2. local overlay: <config>/skills-overlay/<skill-name>/SKILL.md
+`);
+}

package/config.d.ts

@@ -0,0 +1,27 @@
+import { HarnessDirs, SkillsManifest } from '@agentic-kit/harness';
+export declare const DEFAULT_SKILLS_REPO = "constructive-io/constructive-skills";
+export declare const DEFAULT_SKILLS_PIN = "main";
+/** Layer names understood by the assembler. */
+export declare const BASE_LAYER = "constructive-skills";
+export declare const OVERLAY_LAYER = "local-overlay";
+export interface AgentCliConfig {
+    dirs: HarnessDirs;
+    /** pi's agent dir (PI_CODING_AGENT_DIR): `<data>/agent`. */
+    agentDir: string;
+    /** Highest-precedence local skills: `<config>/skills-overlay/`. */
+    overlayDir: string;
+    /** Path of the user-editable manifest: `<config>/skills-manifest.json`. */
+    manifestFile: string;
+    manifest: SkillsManifest;
+    skillsRepo: string;
+    skillsPin: string;
+}
+interface ManifestFile {
+    repo?: string;
+    pin?: string;
+    manifest?: SkillsManifest;
+}
+export declare function defaultManifest(): SkillsManifest;
+export declare function loadConfig(baseDir?: string): AgentCliConfig;
+export declare function saveManifestFile(config: AgentCliConfig, file: ManifestFile): void;
+export {};

package/config.js

@@ -0,0 +1,77 @@
+"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.OVERLAY_LAYER = exports.BASE_LAYER = exports.DEFAULT_SKILLS_PIN = exports.DEFAULT_SKILLS_REPO = void 0;
+exports.defaultManifest = defaultManifest;
+exports.loadConfig = loadConfig;
+exports.saveManifestFile = saveManifestFile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const harness_1 = require("@agentic-kit/harness");
+exports.DEFAULT_SKILLS_REPO = 'constructive-io/constructive-skills';
+exports.DEFAULT_SKILLS_PIN = 'main';
+/** Layer names understood by the assembler. */
+exports.BASE_LAYER = 'constructive-skills';
+exports.OVERLAY_LAYER = 'local-overlay';
+function defaultManifest() {
+    return {
+        sources: [{ name: exports.BASE_LAYER }, { name: exports.OVERLAY_LAYER }]
+    };
+}
+function loadConfig(baseDir) {
+    const dirs = (0, harness_1.harnessDirs)('constructive', baseDir);
+    const agentDir = path.join(dirs.stash.data, 'agent');
+    const overlayDir = path.join(dirs.stash.config, 'skills-overlay');
+    const manifestFile = path.join(dirs.stash.config, 'skills-manifest.json');
+    fs.mkdirSync(agentDir, { recursive: true });
+    fs.mkdirSync(overlayDir, { recursive: true });
+    let file = {};
+    if (fs.existsSync(manifestFile)) {
+        file = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+    }
+    return {
+        dirs,
+        agentDir,
+        overlayDir,
+        manifestFile,
+        manifest: file.manifest ?? defaultManifest(),
+        skillsRepo: process.env.AGENT_SKILLS_REPO ?? file.repo ?? exports.DEFAULT_SKILLS_REPO,
+        skillsPin: process.env.AGENT_SKILLS_PIN ?? file.pin ?? exports.DEFAULT_SKILLS_PIN
+    };
+}
+function saveManifestFile(config, file) {
+    fs.mkdirSync(path.dirname(config.manifestFile), { recursive: true });
+    fs.writeFileSync(config.manifestFile, JSON.stringify(file, null, 2) + '\n');
+}

package/db-tools.d.ts

@@ -0,0 +1,11 @@
+import { AgentCliConfig } from './config';
+/**
+ * Environment variables the generated extension reads at tool-call time.
+ * Without CONSTRUCTIVE_ACCESS_TOKEN the tools load but report "not signed in".
+ */
+export declare const HOST_ENV_VARS: readonly ["CONSTRUCTIVE_USER_ID", "CONSTRUCTIVE_ACCESS_TOKEN", "CONSTRUCTIVE_API_KEY", "CONSTRUCTIVE_API_ENDPOINT", "CONSTRUCTIVE_MODULES_ENDPOINT"];
+/**
+ * Write the db-tools extension entry into pi's agent dir. Returns the file
+ * path, or null when @agentic-kit/pi is not installed alongside the CLI.
+ */
+export declare function materializeDbTools(config: AgentCliConfig, log: (msg: string) => void): string | null;

package/db-tools.js

@@ -0,0 +1,95 @@
+"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.HOST_ENV_VARS = void 0;
+exports.materializeDbTools = materializeDbTools;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const EXTENSION_FILE = 'constructive-db-tools.js';
+/**
+ * Environment variables the generated extension reads at tool-call time.
+ * Without CONSTRUCTIVE_ACCESS_TOKEN the tools load but report "not signed in".
+ */
+exports.HOST_ENV_VARS = [
+    'CONSTRUCTIVE_USER_ID',
+    'CONSTRUCTIVE_ACCESS_TOKEN',
+    'CONSTRUCTIVE_API_KEY',
+    'CONSTRUCTIVE_API_ENDPOINT',
+    'CONSTRUCTIVE_MODULES_ENDPOINT'
+];
+// pi's TUI loads extensions from files under <agentDir>/extensions (via jiti),
+// not from factories, so the db tools are wired by materializing a small
+// generated entry there. The @agentic-kit/pi entry path is resolved from THIS
+// package at assembly time and baked in, because node resolution from the
+// appstash agent dir would not find it.
+function extensionSource(pkgEntry) {
+    return `// Generated by @agentic-kit/cli — do not edit (rewritten on every \`agent\` run).
+// Registers the Constructive typed db tools + confirm gate (@agentic-kit/pi)
+// with credentials read from the environment on each call.
+const { createDbTools } = require(${JSON.stringify(pkgEntry)});
+
+module.exports = createDbTools({
+  account: () => {
+    const userId = process.env.CONSTRUCTIVE_USER_ID;
+    const accessToken = process.env.CONSTRUCTIVE_ACCESS_TOKEN;
+    if (!userId || !accessToken) return null;
+    return { userId, accessToken, apiKey: process.env.CONSTRUCTIVE_API_KEY };
+  },
+  backendConfig: () => ({
+    apiEndpoint: process.env.CONSTRUCTIVE_API_ENDPOINT,
+    modulesEndpoint: process.env.CONSTRUCTIVE_MODULES_ENDPOINT
+  })
+});
+`;
+}
+/**
+ * Write the db-tools extension entry into pi's agent dir. Returns the file
+ * path, or null when @agentic-kit/pi is not installed alongside the CLI.
+ */
+function materializeDbTools(config, log) {
+    let pkgEntry;
+    try {
+        pkgEntry = require.resolve('@agentic-kit/pi');
+    }
+    catch {
+        log('db tools unavailable (@agentic-kit/pi not installed) — continuing without them');
+        return null;
+    }
+    const dir = path.join(config.agentDir, 'extensions');
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, EXTENSION_FILE);
+    fs.writeFileSync(file, extensionSource(pkgEntry));
+    return file;
+}

package/esm/commands.d.ts

@@ -0,0 +1,5 @@
+import { AgentCliConfig } from './config';
+export declare function skillsList(config: AgentCliConfig): Promise<void>;
+export declare function skillsUpdate(config: AgentCliConfig): Promise<void>;
+export declare function init(config: AgentCliConfig, argv: Record<string, unknown>): Promise<void>;
+export declare function usage(): void;

package/esm/commands.js

@@ -0,0 +1,57 @@
+import { Inquirerer } from 'inquirerer';
+import { defaultManifest, saveManifestFile } from './config';
+import { assembleSkills } from './skills';
+const log = (msg) => console.log(`[agent] ${msg}`);
+export async function skillsList(config) {
+    const resolved = await assembleSkills(config, log);
+    if (resolved.length === 0) {
+        console.log('No skills resolved.');
+        return;
+    }
+    for (const skill of resolved) {
+        console.log(`${skill.name}  [${skill.sourceName}]  ${skill.description}`);
+    }
+}
+export async function skillsUpdate(config) {
+    await assembleSkills(config, log);
+}
+export async function init(config, argv) {
+    const prompter = new Inquirerer({ noTty: !process.stdin.isTTY });
+    const answers = await prompter.prompt(argv, [
+        {
+            type: 'text',
+            name: 'repo',
+            message: 'Skills repository (owner/repo)',
+            default: config.skillsRepo
+        },
+        {
+            type: 'text',
+            name: 'pin',
+            message: 'Skills pin (tag, semver range, SHA, or branch)',
+            default: config.skillsPin
+        }
+    ]);
+    saveManifestFile(config, {
+        repo: answers.repo,
+        pin: answers.pin,
+        manifest: defaultManifest()
+    });
+    log(`wrote ${config.manifestFile}`);
+    log(`local overlay dir (highest precedence): ${config.overlayDir}`);
+}
+export function usage() {
+    console.log(`agent — the pi coding agent with the Constructive harness baked in
+
+Usage:
+  agent [pi options...]        start an interactive session (pi TUI)
+  agent -p "prompt"            one-shot print mode (pi)
+  agent init                   configure the skills source (repo + pin)
+  agent skills list            resolve + list the effective skill set
+  agent skills update          re-fetch the base release and re-materialize
+  agent help                   show this help
+
+Skills layering (later wins by skill name, wholesale):
+  1. ${'constructive-skills'} release (git tag/branch/SHA pin, offline fallback)
+  2. local overlay: <config>/skills-overlay/<skill-name>/SKILL.md
+`);
+}

package/esm/config.d.ts

@@ -0,0 +1,27 @@
+import { HarnessDirs, SkillsManifest } from '@agentic-kit/harness';
+export declare const DEFAULT_SKILLS_REPO = "constructive-io/constructive-skills";
+export declare const DEFAULT_SKILLS_PIN = "main";
+/** Layer names understood by the assembler. */
+export declare const BASE_LAYER = "constructive-skills";
+export declare const OVERLAY_LAYER = "local-overlay";
+export interface AgentCliConfig {
+    dirs: HarnessDirs;
+    /** pi's agent dir (PI_CODING_AGENT_DIR): `<data>/agent`. */
+    agentDir: string;
+    /** Highest-precedence local skills: `<config>/skills-overlay/`. */
+    overlayDir: string;
+    /** Path of the user-editable manifest: `<config>/skills-manifest.json`. */
+    manifestFile: string;
+    manifest: SkillsManifest;
+    skillsRepo: string;
+    skillsPin: string;
+}
+interface ManifestFile {
+    repo?: string;
+    pin?: string;
+    manifest?: SkillsManifest;
+}
+export declare function defaultManifest(): SkillsManifest;
+export declare function loadConfig(baseDir?: string): AgentCliConfig;
+export declare function saveManifestFile(config: AgentCliConfig, file: ManifestFile): void;
+export {};

package/esm/config.js

@@ -0,0 +1,38 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { harnessDirs } from '@agentic-kit/harness';
+export const DEFAULT_SKILLS_REPO = 'constructive-io/constructive-skills';
+export const DEFAULT_SKILLS_PIN = 'main';
+/** Layer names understood by the assembler. */
+export const BASE_LAYER = 'constructive-skills';
+export const OVERLAY_LAYER = 'local-overlay';
+export function defaultManifest() {
+    return {
+        sources: [{ name: BASE_LAYER }, { name: OVERLAY_LAYER }]
+    };
+}
+export function loadConfig(baseDir) {
+    const dirs = harnessDirs('constructive', baseDir);
+    const agentDir = path.join(dirs.stash.data, 'agent');
+    const overlayDir = path.join(dirs.stash.config, 'skills-overlay');
+    const manifestFile = path.join(dirs.stash.config, 'skills-manifest.json');
+    fs.mkdirSync(agentDir, { recursive: true });
+    fs.mkdirSync(overlayDir, { recursive: true });
+    let file = {};
+    if (fs.existsSync(manifestFile)) {
+        file = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+    }
+    return {
+        dirs,
+        agentDir,
+        overlayDir,
+        manifestFile,
+        manifest: file.manifest ?? defaultManifest(),
+        skillsRepo: process.env.AGENT_SKILLS_REPO ?? file.repo ?? DEFAULT_SKILLS_REPO,
+        skillsPin: process.env.AGENT_SKILLS_PIN ?? file.pin ?? DEFAULT_SKILLS_PIN
+    };
+}
+export function saveManifestFile(config, file) {
+    fs.mkdirSync(path.dirname(config.manifestFile), { recursive: true });
+    fs.writeFileSync(config.manifestFile, JSON.stringify(file, null, 2) + '\n');
+}

package/esm/db-tools.d.ts

@@ -0,0 +1,11 @@
+import { AgentCliConfig } from './config';
+/**
+ * Environment variables the generated extension reads at tool-call time.
+ * Without CONSTRUCTIVE_ACCESS_TOKEN the tools load but report "not signed in".
+ */
+export declare const HOST_ENV_VARS: readonly ["CONSTRUCTIVE_USER_ID", "CONSTRUCTIVE_ACCESS_TOKEN", "CONSTRUCTIVE_API_KEY", "CONSTRUCTIVE_API_ENDPOINT", "CONSTRUCTIVE_MODULES_ENDPOINT"];
+/**
+ * Write the db-tools extension entry into pi's agent dir. Returns the file
+ * path, or null when @agentic-kit/pi is not installed alongside the CLI.
+ */
+export declare function materializeDbTools(config: AgentCliConfig, log: (msg: string) => void): string | null;

package/esm/db-tools.js

@@ -0,0 +1,58 @@
+import * as fs from 'fs';
+import * as path from 'path';
+const EXTENSION_FILE = 'constructive-db-tools.js';
+/**
+ * Environment variables the generated extension reads at tool-call time.
+ * Without CONSTRUCTIVE_ACCESS_TOKEN the tools load but report "not signed in".
+ */
+export const HOST_ENV_VARS = [
+    'CONSTRUCTIVE_USER_ID',
+    'CONSTRUCTIVE_ACCESS_TOKEN',
+    'CONSTRUCTIVE_API_KEY',
+    'CONSTRUCTIVE_API_ENDPOINT',
+    'CONSTRUCTIVE_MODULES_ENDPOINT'
+];
+// pi's TUI loads extensions from files under <agentDir>/extensions (via jiti),
+// not from factories, so the db tools are wired by materializing a small
+// generated entry there. The @agentic-kit/pi entry path is resolved from THIS
+// package at assembly time and baked in, because node resolution from the
+// appstash agent dir would not find it.
+function extensionSource(pkgEntry) {
+    return `// Generated by @agentic-kit/cli — do not edit (rewritten on every \`agent\` run).
+// Registers the Constructive typed db tools + confirm gate (@agentic-kit/pi)
+// with credentials read from the environment on each call.
+const { createDbTools } = require(${JSON.stringify(pkgEntry)});
+
+module.exports = createDbTools({
+  account: () => {
+    const userId = process.env.CONSTRUCTIVE_USER_ID;
+    const accessToken = process.env.CONSTRUCTIVE_ACCESS_TOKEN;
+    if (!userId || !accessToken) return null;
+    return { userId, accessToken, apiKey: process.env.CONSTRUCTIVE_API_KEY };
+  },
+  backendConfig: () => ({
+    apiEndpoint: process.env.CONSTRUCTIVE_API_ENDPOINT,
+    modulesEndpoint: process.env.CONSTRUCTIVE_MODULES_ENDPOINT
+  })
+});
+`;
+}
+/**
+ * Write the db-tools extension entry into pi's agent dir. Returns the file
+ * path, or null when @agentic-kit/pi is not installed alongside the CLI.
+ */
+export function materializeDbTools(config, log) {
+    let pkgEntry;
+    try {
+        pkgEntry = require.resolve('@agentic-kit/pi');
+    }
+    catch {
+        log('db tools unavailable (@agentic-kit/pi not installed) — continuing without them');
+        return null;
+    }
+    const dir = path.join(config.agentDir, 'extensions');
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, EXTENSION_FILE);
+    fs.writeFileSync(file, extensionSource(pkgEntry));
+    return file;
+}

package/esm/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export { assembleSkills } from './skills';
+export { AgentCliConfig, loadConfig } from './config';
+export { HOST_ENV_VARS, materializeDbTools } from './db-tools';

package/esm/index.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { loadConfig } from './config';
+import { init, skillsList, skillsUpdate, usage } from './commands';
+import { materializeDbTools } from './db-tools';
+import { assembleSkills } from './skills';
+export { assembleSkills } from './skills';
+export { loadConfig } from './config';
+export { HOST_ENV_VARS, materializeDbTools } from './db-tools';
+async function run(args) {
+    const config = loadConfig(process.env.AGENT_HOME);
+    // pi resolves its agent dir (skills, sessions, auth) from this env var;
+    // point it at the appstash-owned dir before the SDK loads.
+    process.env.PI_CODING_AGENT_DIR ??= config.agentDir;
+    const [first, second] = args;
+    if (first === 'help' || first === '--help-agent') {
+        usage();
+        return;
+    }
+    if (first === 'init') {
+        await init(config, {});
+        return;
+    }
+    if (first === 'skills') {
+        if (second === 'update')
+            await skillsUpdate(config);
+        else
+            await skillsList(config);
+        return;
+    }
+    const log = (msg) => console.log(`[agent] ${msg}`);
+    await assembleSkills(config, log);
+    materializeDbTools(config, log);
+    // pi is ESM-only; tsc's CJS output would downlevel a plain `await import()`
+    // into `require()`, which cannot load it. Indirect the import so it survives
+    // transpilation in the CJS build.
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    const { main } = await dynamicImport('@earendil-works/pi-coding-agent');
+    await main(args);
+}
+if (require.main === module) {
+    run(process.argv.slice(2)).catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    });
+}

package/esm/skills.d.ts

@@ -0,0 +1,8 @@
+import { HarnessSkill } from '@agentic-kit/harness';
+import { AgentCliConfig } from './config';
+/**
+ * Assemble the effective skill tree (fetched base + local overlay, later
+ * layer wins wholesale by skill name) into pi's agent dir so the session
+ * picks it up as regular skills.
+ */
+export declare function assembleSkills(config: AgentCliConfig, log?: (msg: string) => void): Promise<HarnessSkill[]>;

package/esm/skills.js

@@ -0,0 +1,59 @@
+import * as path from 'path';
+import { DirectorySkillSource, fetchSkillsFromGit, latestLocalRelease, materializeSkills, resolveSkills } from '@agentic-kit/harness';
+import { BASE_LAYER, OVERLAY_LAYER } from './config';
+/** An empty layer so a missing/unavailable source never breaks assembly. */
+class EmptySkillSource {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+    async load() {
+        return [];
+    }
+}
+async function baseSource(config, log) {
+    try {
+        const release = await fetchSkillsFromGit({
+            repo: config.skillsRepo,
+            pin: config.skillsPin,
+            skillsRoot: config.dirs.skillsRoot,
+            token: process.env.GITHUB_TOKEN
+        });
+        log(`skills base: ${config.skillsRepo}@${release.version}${release.fromCache ? ' (cached)' : ''}`);
+        return new DirectorySkillSource(BASE_LAYER, release.skillsDir);
+    }
+    catch (error) {
+        const local = latestLocalRelease(config.dirs.skillsRoot);
+        if (local) {
+            log(`skills base: offline fallback to local release ${local.version} (${error.message})`);
+            return new DirectorySkillSource(BASE_LAYER, local.skillsDir);
+        }
+        log(`skills base: unavailable, continuing without it (${error.message})`);
+        return new EmptySkillSource(BASE_LAYER);
+    }
+}
+/**
+ * Assemble the effective skill tree (fetched base + local overlay, later
+ * layer wins wholesale by skill name) into pi's agent dir so the session
+ * picks it up as regular skills.
+ */
+export async function assembleSkills(config, log = () => undefined) {
+    const sources = [];
+    for (const ref of config.manifest.sources) {
+        if (ref.name === BASE_LAYER) {
+            sources.push(await baseSource(config, log));
+        }
+        else if (ref.name === OVERLAY_LAYER) {
+            sources.push(new DirectorySkillSource(OVERLAY_LAYER, config.overlayDir));
+        }
+        else {
+            throw new Error(`Unknown manifest source: ${ref.name}`);
+        }
+    }
+    const resolved = await resolveSkills(config.manifest, sources, {
+        onMissingRequire: (skill, required) => log(`skill ${skill} requires missing skill ${required}`)
+    });
+    materializeSkills(path.join(config.agentDir, 'skills'), resolved);
+    log(`skills materialized: ${resolved.map((s) => s.name).join(', ') || '(none)'}`);
+    return resolved;
+}

package/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export { assembleSkills } from './skills';
+export { AgentCliConfig, loadConfig } from './config';
+export { HOST_ENV_VARS, materializeDbTools } from './db-tools';

package/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.materializeDbTools = exports.HOST_ENV_VARS = exports.loadConfig = exports.assembleSkills = void 0;
+const config_1 = require("./config");
+const commands_1 = require("./commands");
+const db_tools_1 = require("./db-tools");
+const skills_1 = require("./skills");
+var skills_2 = require("./skills");
+Object.defineProperty(exports, "assembleSkills", { enumerable: true, get: function () { return skills_2.assembleSkills; } });
+var config_2 = require("./config");
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_2.loadConfig; } });
+var db_tools_2 = require("./db-tools");
+Object.defineProperty(exports, "HOST_ENV_VARS", { enumerable: true, get: function () { return db_tools_2.HOST_ENV_VARS; } });
+Object.defineProperty(exports, "materializeDbTools", { enumerable: true, get: function () { return db_tools_2.materializeDbTools; } });
+async function run(args) {
+    const config = (0, config_1.loadConfig)(process.env.AGENT_HOME);
+    // pi resolves its agent dir (skills, sessions, auth) from this env var;
+    // point it at the appstash-owned dir before the SDK loads.
+    process.env.PI_CODING_AGENT_DIR ??= config.agentDir;
+    const [first, second] = args;
+    if (first === 'help' || first === '--help-agent') {
+        (0, commands_1.usage)();
+        return;
+    }
+    if (first === 'init') {
+        await (0, commands_1.init)(config, {});
+        return;
+    }
+    if (first === 'skills') {
+        if (second === 'update')
+            await (0, commands_1.skillsUpdate)(config);
+        else
+            await (0, commands_1.skillsList)(config);
+        return;
+    }
+    const log = (msg) => console.log(`[agent] ${msg}`);
+    await (0, skills_1.assembleSkills)(config, log);
+    (0, db_tools_1.materializeDbTools)(config, log);
+    // pi is ESM-only; tsc's CJS output would downlevel a plain `await import()`
+    // into `require()`, which cannot load it. Indirect the import so it survives
+    // transpilation in the CJS build.
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    const { main } = await dynamicImport('@earendil-works/pi-coding-agent');
+    await main(args);
+}
+if (require.main === module) {
+    run(process.argv.slice(2)).catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@agentic-kit/cli",
+  "version": "0.2.0",
+  "author": "Dan Lynch <pyramation@gmail.com>",
+  "description": "agent — the pi coding agent with the Constructive harness baked in, purely a shell",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "agent": "index.js"
+  },
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@agentic-kit/harness": "0.3.0",
+    "@agentic-kit/pi": "0.2.0",
+    "@earendil-works/pi-coding-agent": "0.79.6",
+    "inquirerer": "^4.9.1"
+  },
+  "keywords": [
+    "agentic-kit",
+    "coding-agent",
+    "pi",
+    "harness"
+  ],
+  "gitHead": "31f7cd3d3cc28cf069056eae5b2a0d4198d154a1"
+}

package/skills.d.ts

@@ -0,0 +1,8 @@
+import { HarnessSkill } from '@agentic-kit/harness';
+import { AgentCliConfig } from './config';
+/**
+ * Assemble the effective skill tree (fetched base + local overlay, later
+ * layer wins wholesale by skill name) into pi's agent dir so the session
+ * picks it up as regular skills.
+ */
+export declare function assembleSkills(config: AgentCliConfig, log?: (msg: string) => void): Promise<HarnessSkill[]>;

package/skills.js

@@ -0,0 +1,95 @@
+"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.assembleSkills = assembleSkills;
+const path = __importStar(require("path"));
+const harness_1 = require("@agentic-kit/harness");
+const config_1 = require("./config");
+/** An empty layer so a missing/unavailable source never breaks assembly. */
+class EmptySkillSource {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+    async load() {
+        return [];
+    }
+}
+async function baseSource(config, log) {
+    try {
+        const release = await (0, harness_1.fetchSkillsFromGit)({
+            repo: config.skillsRepo,
+            pin: config.skillsPin,
+            skillsRoot: config.dirs.skillsRoot,
+            token: process.env.GITHUB_TOKEN
+        });
+        log(`skills base: ${config.skillsRepo}@${release.version}${release.fromCache ? ' (cached)' : ''}`);
+        return new harness_1.DirectorySkillSource(config_1.BASE_LAYER, release.skillsDir);
+    }
+    catch (error) {
+        const local = (0, harness_1.latestLocalRelease)(config.dirs.skillsRoot);
+        if (local) {
+            log(`skills base: offline fallback to local release ${local.version} (${error.message})`);
+            return new harness_1.DirectorySkillSource(config_1.BASE_LAYER, local.skillsDir);
+        }
+        log(`skills base: unavailable, continuing without it (${error.message})`);
+        return new EmptySkillSource(config_1.BASE_LAYER);
+    }
+}
+/**
+ * Assemble the effective skill tree (fetched base + local overlay, later
+ * layer wins wholesale by skill name) into pi's agent dir so the session
+ * picks it up as regular skills.
+ */
+async function assembleSkills(config, log = () => undefined) {
+    const sources = [];
+    for (const ref of config.manifest.sources) {
+        if (ref.name === config_1.BASE_LAYER) {
+            sources.push(await baseSource(config, log));
+        }
+        else if (ref.name === config_1.OVERLAY_LAYER) {
+            sources.push(new harness_1.DirectorySkillSource(config_1.OVERLAY_LAYER, config.overlayDir));
+        }
+        else {
+            throw new Error(`Unknown manifest source: ${ref.name}`);
+        }
+    }
+    const resolved = await (0, harness_1.resolveSkills)(config.manifest, sources, {
+        onMissingRequire: (skill, required) => log(`skill ${skill} requires missing skill ${required}`)
+    });
+    (0, harness_1.materializeSkills)(path.join(config.agentDir, 'skills'), resolved);
+    log(`skills materialized: ${resolved.map((s) => s.name).join(', ') || '(none)'}`);
+    return resolved;
+}