@hadooppei/hwcode 0.1.0

package/.pi/skills/hwcode-vibe/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: hwcode-vibe
+description: Run a directory-locked, conversational vibe-coding workflow for starting or evolving a software project through small, continuously verified increments. Use when the user invokes /hwcode-vibe or explicitly wants iterative collaborative coding without a formal specification phase.
+---
+
+# HWCode Vibe
+
+Build with the user in short feedback loops while preserving a clear project boundary.
+
+## Verify activation
+
+Confirm that the activation message states a locked project root. If this skill was invoked directly without the `/hwcode-vibe` project command, do not begin project work; ask the user to run `/hwcode-vibe [initial request]` so the extension can confirm and enforce the directory boundary.
+
+Treat the locked root as the only project workspace for the entire session. Use paths inside it without extra confirmation. When a tool asks for one-call approval for an external path such as `/tmp`, explain the concrete need and let the user decide. Never bypass that guard through a subprocess, symlink, encoding, or another tool.
+
+## Establish the starting point
+
+Inspect project instructions and relevant files before changing code.
+
+For an empty or new project:
+
+1. Identify the intended users, primary outcome, target platform, hard constraints, smallest useful version, and definition of done.
+2. Ask only questions that block the first coherent increment.
+3. Recommend a suitable stack with brief tradeoffs instead of silently choosing consequential architecture.
+4. Confirm the first thin vertical slice before building it.
+
+For an existing project, identify its entry points, conventions, commands, tests, and current behavior. Reuse existing patterns unless there is a clear reason to change them.
+
+## Run the collaboration loop
+
+Repeat this loop until the user stops or changes direction:
+
+1. Restate the immediate outcome and any important assumption in a few lines.
+2. Keep a lightweight conversational backlog; select one small, end-to-end increment.
+3. Implement the smallest coherent change that makes that increment useful.
+4. Verify it with the narrowest relevant tests, type checks, builds, or direct behavior checks.
+5. Inspect the result, fix regressions, and report what now works.
+6. Ask for feedback or propose the next highest-value increment.
+
+Prefer working software over speculative framework construction. Keep interfaces simple, dependencies minimal, and changes easy to reverse. Preserve user changes and do not rewrite unrelated code.
+
+## Apply engineering discipline
+
+- Add or update tests in proportion to risk. Cover important failure and boundary behavior, not only the happy path.
+- Follow repository formatting, naming, dependency, and error-handling conventions.
+- Never expose or commit credentials, local sessions, `.env` contents, or private data.
+- Ask before major architecture changes, new paid/external services, destructive actions, migrations with data risk, publishing, or commits.
+- For UI work, verify both behavior and the important visual states when practical.
+- If verification cannot run, state exactly what is unverified and why.
+- Suggest Git checkpoints at stable milestones, but create a commit only when the user explicitly requests or approves it.
+
+Keep the conversation adaptive. Do not impose the SDD artifact set unless the user switches to `/hwcode-sdd`.

package/.pi/skills/hwcode-vibe/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HWCode Vibe"
+  short_description: "Iterative collaborative vibe-coding workflow"
+  default_prompt: "Use $hwcode-vibe to build a project iteratively with me."

package/.pi/welcome.json

@@ -0,0 +1,15 @@
+{
+  "title": "HWCode · Pi",
+  "logo": "HWCODE",
+  "characterColors": [
+    "accent",
+    "success",
+    "warning",
+    "accent",
+    "success",
+    "warning"
+  ],
+  "subtitle": "Local AI Coding Workspace",
+  "subtitleColor": "muted",
+  "reservedRows": 8
+}

package/README.md

@@ -0,0 +1,145 @@
+# HWCode
+
+A customizable terminal coding agent built on Pi, with local-model providers,
+persistent working directories, a tailored TUI, and Vibe/SDD workflows.
+
+## Install
+
+HWCode requires Node.js 22.19 or newer. Install it globally from npm:
+
+```sh
+npm install --global @hadooppei/hwcode
+```
+
+Then start it from the project directory you want to work in:
+
+```sh
+cd your-project
+hwcode
+```
+
+`npx @hadooppei/hwcode` is also supported without a global installation. HWCode loads a
+project's `.env` file when present and keeps Pi's normal user-level auth and
+session storage. Project-local `.pi` resources continue to load alongside the
+built-in HWCode profile.
+
+## Repository setup
+
+```sh
+npm install --ignore-scripts
+cp .env.example .env
+npm start
+```
+
+On first launch, review and accept Pi's project-trust prompt so it can load the resources under `.pi/`.
+
+## Model providers
+
+OpenAI-compatible providers are declared in `.pi/model-providers.json`.
+Static providers list their models directly:
+
+```json
+{
+  "id": "local-example",
+  "name": "Local example",
+  "baseUrl": "http://127.0.0.1:8082",
+  "apiKeyEnv": "PI_LOCAL_MODEL_API_KEY",
+  "models": [
+    {
+      "id": "model-id",
+      "input": ["text", "image"],
+      "contextWindow": 32768,
+      "maxTokens": 8192
+    }
+  ]
+}
+```
+
+Login providers use Pi's native `/login` flow and discover every model exposed
+by an OpenAI-compatible model endpoint:
+
+```json
+{
+  "id": "hw",
+  "name": "hw",
+  "baseUrl": "http://127.0.0.1:8080/v1",
+  "apiKeyEnv": "HW_API_KEY",
+  "login": {
+    "enabled": true,
+    "promptBaseUrl": true,
+    "promptApiKey": true,
+    "apiKeyRequired": false,
+    "catalogPath": "models"
+  },
+  "modelDefaults": {
+    "input": ["text"],
+    "contextWindow": 32768,
+    "maxTokens": 8192
+  }
+}
+```
+
+`id` is the stable credential and cache key; `name` is the configurable label
+shown alongside other providers in `/login`. A login authenticates the whole
+provider and publishes its complete model catalog to `/model`. Entries in a
+login provider's `models` array are optional metadata overrides for discovered
+IDs, which is where vision support should be declared with
+`"input": ["text", "image"]`. Unknown models default to text-only. Keep real
+API keys in `.env` or enter them through `/login`; Pi stores entered credentials
+in its own auth store rather than the project configuration.
+
+## Welcome screen
+
+The responsive vector-rasterized Braille pixel logo is configured in `.pi/welcome.json`.
+`logo` accepts 1-6 English letters. `characterColors` contains Pi theme color
+names and cycles when fewer colors than characters are provided. The logo scales
+and centers itself whenever the fullscreen terminal is resized. The first
+submitted prompt removes the welcome UI before the conversation is rendered.
+
+## Development workflows
+
+Start one of the project workflows from the Pi input:
+
+```text
+/hwcode-vibe Build a small web application with me
+/hwcode-sdd Add role-based access control
+```
+
+Both commands first confirm the current directory and lock project work to that
+root for the session. In-root operations run normally; each tool call that names
+an external path asks for separate approval. `/hwcode-vibe` uses short iterative
+build-and-verify loops. `/hwcode-sdd` additionally requires the current directory
+to be the Git repository root, inventories the codebase, resolves requirement
+questions, and persists approved artifacts under
+`.hwcode/specs/<requirement-slug>/` before test-first implementation begins.
+
+## Working directory
+
+Use `/cd <path>` to change the working directory without starting a new
+session. A leading `cd` in either an agent shell call or a user `!` shell
+command has the same persistent behavior. Subsequent shell commands, built-in
+file tools, the Footer, and workflow activation all use the updated directory.
+The directory is stored in the session and restored when that session resumes;
+`cd -` returns to its previous directory. An active HWCode workflow keeps its
+directory lock and rejects changes to another root.
+
+## Command visibility
+
+The `hwcode.hiddenCommands` array in `.pi/settings.json` removes selected
+commands from slash-command autocomplete. Store names without the leading `/`;
+skill commands use names such as `skill:hwcode-vibe`. An empty array shows every
+command. Restart Pi or manually enter `/reload` after changing the list.
+
+This setting controls visibility, not capability. A hidden command can still be
+entered manually when it is needed.
+
+## Project resources
+
+- `AGENTS.md`: project-wide working rules
+- `.pi/settings.json`: project-level Pi settings
+- `.pi/APPEND_SYSTEM.md`: additions to the system prompt
+- `.pi/extensions/`: TypeScript extensions
+- `.pi/skills/`: reusable workflows
+- `.pi/prompts/`: slash-command prompt templates
+
+Credentials must not be committed. Use environment variables or Pi's user-level authentication store.

package/bin/hwcode.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const profileDirectory = join(packageRoot, ".pi");
+const piCli = join(
+	packageRoot,
+	"node_modules",
+	"@earendil-works",
+	"pi-coding-agent",
+	"dist",
+	"cli.js",
+);
+const userArgs = process.argv.slice(2);
+if (userArgs[0] === "--version" || userArgs[0] === "-v") {
+	const packageJson = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+	console.log(packageJson.version);
+	process.exit(0);
+}
+const piManagementCommands = new Set([
+	"--help",
+	"-h",
+	"auth",
+	"config",
+	"install",
+	"list",
+	"remove",
+	"uninstall",
+	"update",
+]);
+
+const profileArgs = [
+	"--tui-mode",
+	"fullscreen",
+	"--thinking",
+	"medium",
+	"--append-system-prompt",
+	join(profileDirectory, "APPEND_SYSTEM.md"),
+];
+
+for (const extension of [
+	"command-filter.ts",
+	"cwd.ts",
+	"footer-tps.ts",
+	"hwcode.ts",
+	"model-providers.ts",
+	"welcome.ts",
+	"workflows.ts",
+]) {
+	profileArgs.push("--extension", join(profileDirectory, "extensions", extension));
+}
+
+for (const skill of ["hwcode-vibe", "hwcode-sdd"]) {
+	profileArgs.push("--skill", join(profileDirectory, "skills", skill));
+}
+
+const args = piManagementCommands.has(userArgs[0]) ? userArgs : [...profileArgs, ...userArgs];
+const projectEnvPath = join(process.cwd(), ".env");
+const nodeArgs = existsSync(projectEnvPath) ? [`--env-file=${projectEnvPath}`] : [];
+const child = spawn(
+	process.execPath,
+	[...nodeArgs, piCli, ...args],
+	{
+		cwd: process.cwd(),
+		env: { ...process.env, HWCODE_PROFILE_DIR: profileDirectory },
+		stdio: "inherit",
+	},
+);
+
+child.on("error", (error) => {
+	console.error(`Unable to start HWCode: ${error.message}`);
+	process.exitCode = 1;
+});
+
+child.on("exit", (code, signal) => {
+	if (signal) {
+		process.kill(process.pid, signal);
+		return;
+	}
+	process.exitCode = code ?? 1;
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@hadooppei/hwcode",
+  "version": "0.1.0",
+  "description": "A customizable terminal coding agent with local-model support and HWCode workflows.",
+  "type": "module",
+  "bin": {
+    "hwcode": "bin/hwcode.js"
+  },
+  "files": [
+    "bin/hwcode.js",
+    ".env.example",
+    ".pi/APPEND_SYSTEM.md",
+    ".pi/extensions",
+    ".pi/lib/command-filter.ts",
+    ".pi/lib/pixel-font.ts",
+    ".pi/lib/welcome-input.ts",
+    ".pi/lib/workflow-guard.ts",
+    ".pi/lib/working-directory.ts",
+    ".pi/model-providers.json",
+    ".pi/skills/hwcode-sdd",
+    ".pi/skills/hwcode-vibe",
+    ".pi/welcome.json",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node --env-file-if-exists=.env ./bin/hwcode.js",
+    "pi": "node --env-file-if-exists=.env ./bin/hwcode.js",
+    "test": "node --test .pi/lib/*.test.ts",
+    "test:workflows": "npm test",
+    "prepack": "npm test"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "cli",
+    "local-llm",
+    "pi",
+    "spec-driven-development",
+    "vibe-coding"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.2"
+  }
+}