solo-cto-agent 0.5.1

package/CHANGELOG

@@ -0,0 +1,46 @@
+# Changelog
+
+## 0.5.1
+
+* added skill slimming docs (references/ pattern with measured results)
+* fixed BOM encoding in CONTRIBUTING
+* fixed corrupted FAQ section in README
+* cleaned up README: removed duplicate sections, consolidated post-install guide
+* updated ROADMAP with v0.5.0 completion and v0.6.0 plan
+
+## 0.5.0
+
+* added CLI init/status commands for npm distribution
+* added demo asset, architecture diagram, and updated Quick Start
+* expanded CONTRIBUTING and templates
+
+## 0.4.0
+
+* added package.json and basic test tooling
+* added failure-catalog.json and schema validation
+* added CI test workflow for PRs
+* added ROADMAP.md
+
+## 0.3.0
+
+* added .cursorrules for Cursor IDE support
+* added .windsurfrules for Windsurf (Cascade) support
+* added .github/copilot-instructions.md for GitHub Copilot support
+* all three rule files share the same CTO philosophy, adapted to each tool's format
+
+## 0.2.0
+
+* rewrote README to sound more human and less sales-heavy
+* improved `setup.sh` toward safer repeat installs and updates
+* softened over-strong automation claims in `build`
+* clarified `craft` as intentionally opinionated
+* tightened `review` wording
+* added contribution guidance
+* added example files for practical usage
+
+## 0.1.0
+
+* initial public release
+* added build, ship, craft, spark, review, and memory skills
+* added setup script
+* added templates for context and project state

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seunghunbae-3svs
+
+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,409 @@
+# solo-cto-agent
+
+[![npm](https://img.shields.io/npm/v/solo-cto-agent)](https://www.npmjs.com/package/solo-cto-agent)
+[![Package Validate](https://github.com/seunghunbae-3svs/solo-cto-agent/actions/workflows/package-validate.yml/badge.svg)](https://github.com/seunghunbae-3svs/solo-cto-agent/actions/workflows/package-validate.yml)
+[![Test](https://github.com/seunghunbae-3svs/solo-cto-agent/actions/workflows/test.yml/badge.svg)](https://github.com/seunghunbae-3svs/solo-cto-agent/actions/workflows/test.yml)
+[![Changelog](https://github.com/seunghunbae-3svs/solo-cto-agent/actions/workflows/changelog.yml/badge.svg)](https://github.com/seunghunbae-3svs/solo-cto-agent/actions/workflows/changelog.yml)
+[![License](https://img.shields.io/github/license/seunghunbae-3svs/solo-cto-agent)](LICENSE)
+
+
+I made this because I got tired of using AI coding tools that were good at writing code, but still left me doing all the messy CTO work around it.
+
+The hard part was rarely "write the feature." It was everything around the feature:
+
+* catching missing env vars before a deploy breaks
+* not re-explaining the same stack every new session
+* stopping error loops before they waste half an hour
+* getting honest pushback on ideas instead of empty encouragement
+* cleaning up UI that looks obviously AI-generated
+
+This repo is my attempt to package those habits into a small set of reusable skills. It is not magic. It is not a replacement for judgment. It is just a better operating system for the kind of AI agent I wanted to work with.
+
+## What this is
+
+`solo-cto-agent` is an opinionated skill pack for solo founders, indie hackers, and small teams using AI coding agents in their build workflow.
+
+Primary workflow: Cowork + Codex.  
+It was built around Claude Code & OpenAI Codex but the core rules also work in Cursor, Windsurf, and GitHub Copilot. The repo includes native config files where needed.
+
+The point is simple:
+
+* less repetitive setup work
+* less context loss between sessions
+* less AI slop in code and design
+* more useful criticism before you commit to bad ideas
+* more initiative from the agent on low-risk work
+
+## What changes in practice
+
+This is the difference I wanted in day-to-day use:
+
+| Without this | With this |
+| -------------------------------------------- | -------------------------------------------------------------- |
+| Same build error over and over | Circuit breaker stops the loop and summarizes the likely cause |
+| "Please add this manually to your dashboard" | Agent checks setup earlier and asks once when needed |
+| New session, same explanation again | Important decisions get reused |
+| Rounded-blue-gradient AI UI | Design checks push for more intentional output |
+| "Looks good to me" feedback | Review forces actual criticism |
+| Agent asks permission for every tiny step | Low-risk work gets done without constant back-and-forth |
+
+## Who this is for
+
+This repo is probably useful if you:
+
+* build mostly alone or with a very small team
+* already use Claude, Codex, Cursor, Windsurf, or Copilot in your workflow
+* want the agent to take more initiative
+* care about startup execution, not just code completion
+* are okay with opinionated defaults
+
+It is probably not a good fit if you:
+
+* work in a tightly locked-down enterprise environment
+* do not want agents touching files or setup
+* want every action manually approved
+* prefer a neutral framework-agnostic starter pack with very conservative defaults
+
+## What's inside
+
+```text
+solo-cto-agent/
+├── autopilot.md
+├── .cursorrules              ← Cursor picks this up automatically
+├── .windsurfrules            ← Windsurf (Cascade) picks this up automatically
+├── .github/
+│   └── copilot-instructions.md  ← GitHub Copilot workspace instructions
+├── skills/
+│   ├── build/
+│   │   └── SKILL.md
+│   ├── ship/
+│   │   └── SKILL.md
+│   ├── craft/
+│   │   └── SKILL.md
+│   ├── spark/
+│   │   └── SKILL.md
+│   ├── review/
+│   │   └── SKILL.md
+│   └── memory/
+│       └── SKILL.md
+└── templates/
+    ├── project.md
+    └── context.md
+```
+
+## 5-Minute Quick Start
+
+Three steps, under two minutes:
+
+1) Install the CLI
+```bash
+npx solo-cto-agent init
+```
+
+2) Configure your stack
+```text
+Open ~/.claude/skills/solo-cto-agent/SKILL.md
+Replace the {{YOUR_*}} placeholders
+```
+
+3) Verify
+```bash
+solo-cto-agent status
+```
+
+Expected output looks like:
+```text
+solo-cto-agent status
+- SKILL.md: OK
+- failure-catalog.json: OK
+- error patterns: 8
+```
+
+## Demo
+
+![CLI demo](docs/demo.svg)
+
+## Architecture
+
+```mermaid
+graph LR
+  A[Error Detected] --> B[failure-catalog.json]
+  B --> C[Pattern Match]
+  C --> D[Auto-Fix Applied]
+  D --> E[Build Verified]
+```
+
+## Install
+
+### npm (recommended)
+
+```bash
+npm install -g solo-cto-agent
+solo-cto-agent init
+```
+
+### Quick install (Claude Code)
+
+```bash
+curl -sSL https://raw.githubusercontent.com/seunghunbae-3svs/solo-cto-agent/main/setup.sh | bash
+```
+
+### Manual install
+
+```bash
+git clone https://github.com/seunghunbae-3svs/solo-cto-agent.git
+cp -r solo-cto-agent/skills/* ~/.claude/skills/
+cat solo-cto-agent/autopilot.md >> ~/.claude/CLAUDE.md
+```
+
+### Only want one skill?
+
+```bash
+cp -r solo-cto-agent/skills/build ~/.claude/skills/
+```
+
+Then open the skill file and replace the placeholders with your actual stack. Example:
+
+```text
+{{YOUR_OS}}        -> macOS / Windows / Linux
+{{YOUR_EDITOR}}    -> Cursor / VSCode / etc.
+{{YOUR_DEPLOY}}    -> Vercel / Railway / Netlify / etc.
+{{YOUR_FRAMEWORK}} -> Next.js / Remix / SvelteKit / etc.
+```
+
+### Using with Cowork + Codex
+
+Codex is a first-class target. Use the SKILL.md files directly as your instruction source. No extra Codex-specific files are required.
+
+### Using with Codex, Cursor, Windsurf, or Copilot
+
+If you use Codex, Cursor, Windsurf, or GitHub Copilot instead of (or alongside) Claude, the repo includes native rule files:
+
+* `.cursorrules` - Cursor reads this from your project root automatically
+* `.windsurfrules` - Windsurf (Cascade) reads this from your project root automatically
+* `.github/copilot-instructions.md` - GitHub Copilot reads this as workspace-level instructions
+
+Just copy the files you need into your project:
+
+```bash
+cp solo-cto-agent/.cursorrules ./
+cp solo-cto-agent/.windsurfrules ./
+cp -r solo-cto-agent/.github ./
+```
+
+These files contain the same CTO philosophy as the Claude skills - autonomy levels, build discipline, design standards, review rules - adapted to each tool's format. They are not watered-down versions. They are the same operating system, just in a different config file.
+
+## How I use autonomy
+
+Most agent workflows feel too timid in the wrong places and too reckless in the dangerous ones. So I split behavior into 3 levels.
+
+### L1 - just do it
+
+Small, low-risk work should not need approval. Examples:
+
+* fixing typos
+* creating obvious files
+* loading context
+* choosing an output format
+* doing routine search or setup checks
+
+### L2 - do it, then explain
+
+If something is a bit ambiguous but still low-risk, the agent makes the best assumption, does the work, and tells me what it assumed. That is usually better than spending 10 messages clarifying something that could have been resolved in one pass.
+
+### L3 - ask first
+
+Some things still need explicit approval:
+
+* production deploys
+* schema changes
+* cost-increasing decisions
+* anything sent under my name
+* actions that could cause irreversible damage
+
+That split has worked much better for me than asking permission every 30 seconds.
+
+## Skills
+
+### build
+
+This is the one I use most. Its job is to reduce the annoying parts of implementation work:
+
+* check prerequisites before coding
+* catch missing env vars, packages, migrations, or config earlier
+* keep scope from drifting
+* stop repeated error loops
+* keep build and deploy problems from bouncing back to the user too quickly
+
+The core idea is simple:
+
+> do more of the setup thinking before writing code, not after something fails.
+
+### ship
+
+The job is not done when the code is written. It is done when the deploy works.
+
+This skill treats deploy failures as part of the work:
+
+* monitor the build
+* read the logs
+* try reasonable fixes
+* stop when a circuit breaker is hit
+* escalate clearly instead of spiraling
+
+### craft
+
+This exists because AI-generated UI often has a very obvious look. Too many gradients. Too much rounded everything. Too many generic SaaS defaults that look "fine" but still feel cheap.
+
+This skill is an opinionated design filter:
+
+* typography rules
+* color discipline
+* spacing consistency
+* motion sanity
+* anti-slop checks
+
+It does not guarantee great design, but it helps avoid lazy AI design.
+
+### spark
+
+For idea work, I wanted something better than "this market is huge."
+
+This skill takes an early idea and forces it through structure:
+
+* market scan
+* competitors
+* unit economics
+* scenarios
+* risk framing
+* PRD direction
+
+Useful when an idea is still vague but you need something more testable.
+
+### review
+
+This skill is intentionally not friendly. It looks at a plan from three perspectives:
+
+* investor
+* target user
+* smart competitor
+
+The point is to expose weak points early, not to make the founder feel good.
+
+### memory
+
+This is for reducing repeat explanation and preserving useful context.
+
+Not everything needs to be remembered forever. But decisions, repeated failure patterns, and project context should not disappear every session.
+
+## Skill slimming
+
+When skills grow past 150 lines, most of that weight is reference data the agent doesn't need on every activation. The `references/` pattern splits hot-path logic from cold-path data, cutting token costs by 58-79% per skill without losing functionality.
+
+See [docs/skill-slimming.md](docs/skill-slimming.md) for the pattern, measured results, and how to apply it.
+
+## Design principles
+
+### Agent does the work, user makes decisions
+
+If the agent can reasonably figure something out, it should do that. The user should spend time on judgment calls, not repetitive setup.
+
+### Risks before strengths
+
+Good review starts with what is broken, vague, or contradictory. Praise comes after that.
+
+### Facts over vibes
+
+If a number appears, it should have a source, a formula, or a clear label like:
+
+* `[confirmed]`
+* `[estimated]`
+* `[unverified]`
+
+### Pre-scan, don't surprise
+
+A lot of agent frustration comes from late discovery: missing env vars, missing package installs, missing DB changes, missing credentials. This pack tries to catch those earlier.
+
+### Keep the loop bounded
+
+If the same problem keeps happening, stop and report clearly. An agent that loops forever is worse than one that asks for help.
+
+## What this is not
+
+This is not:
+
+* a hosted product
+* a full framework
+* a universal standard for agent behavior
+* a replacement for technical judgment
+
+It is just a set of operating rules that worked well enough for me to package and share.
+
+## Recommended first use
+
+If you want to try this without changing your whole workflow:
+
+1. install only `build` and `review`
+2. replace the stack placeholders
+3. use them on one real feature or bug
+4. see whether the agent becomes more useful or just more opinionated
+
+That is the easiest way to tell whether this fits how you work.
+
+## License
+
+MIT - fork it, modify it, ship it.
+
+
+---
+
+## Post-install verification
+
+After installation, verify the pack works:
+
+1. Check skills exist in your agent directory (e.g. `~/.claude/skills`)
+2. Confirm each skill has valid frontmatter (`---` block)
+3. Run a simple prompt like "Use build to fix a TypeScript error"
+4. Run `bash scripts/validate.sh` to check file integrity
+5. Confirm no auto-merge or deploy happens without approval
+
+If something fails, re-run `setup.sh --update` and check again.
+
+
+---
+
+## Sample output
+
+**Build (preflight + fix)**
+```
+[build] pre-scan: missing env vars: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
+[build] request: please provide the 2 keys above before proceeding
+[build] applied: fixed prisma client mismatch
+[build] build: npm run build -> OK
+[build] report: 3 files changed, 1 risk flagged, rollback path noted
+```
+
+**Review + rework**
+```
+[review] Codex: REQUEST_CHANGES (blocker: missing RLS policy)
+[review] Claude: APPROVE (nits: copy, spacing)
+[rework] round 1/2 -> fixed RLS policy + added tests
+[decision] recommendation: HOLD until preview verified
+```
+
+
+---
+
+## FAQ
+
+**Q: Do I need all six skills?**
+A: No. Start with `build` and `review`. Add the others if you find yourself wanting them. Each skill is independent.
+
+**Q: Why does the agent stop retrying after 3 attempts?**
+A: Infinite loops waste more time than they save. If something fails 3 times, the agent summarizes what it knows and hands control back to you.
+
+**Q: Why is the design skill so opinionated?**
+A: Because default AI output tends toward the same rounded-gradient look. The rules push for more intentional choices. Override whatever doesn't fit your taste.
+
+**Q: Does this work in Cursor/Windsurf?**
+A: Yes. The repo includes native config files for each. The core philosophy is the same across all tools.

package/bin/cli.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const https = require("https");
+
+const ROOT = path.resolve(__dirname, "..");
+const DEFAULT_CATALOG = path.join(ROOT, "failure-catalog.json");
+
+function printHelp() {
+  console.log(`solo-cto-agent
+
+Usage:
+  solo-cto-agent init [--force]
+  solo-cto-agent status
+  solo-cto-agent --help
+
+Commands:
+  init     scaffold ~/.claude/skills/solo-cto-agent
+  status   check skill health and error catalog
+`);
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeFileIfMissing(filePath, content, force) {
+  if (fs.existsSync(filePath) && !force) {
+    return false;
+  }
+  fs.writeFileSync(filePath, content, "utf8");
+  return true;
+}
+
+function initCommand(force) {
+  const targetDir = path.join(os.homedir(), ".claude", "skills", "solo-cto-agent");
+  ensureDir(targetDir);
+
+  // Copy failure-catalog.json
+  const targetCatalog = path.join(targetDir, "failure-catalog.json");
+  const catalogContent = fs.readFileSync(DEFAULT_CATALOG, "utf8");
+  const catalogWritten = writeFileIfMissing(targetCatalog, catalogContent, force);
+
+  // Create starter SKILL.md
+  const targetSkill = path.join(targetDir, "SKILL.md");
+  const starter = `---
+name: solo-cto-agent
+description: "Project-specific CTO skill pack. Replace placeholders with real stack info."
+user-invocable: true
+---
+
+# Project Stack
+
+OS: {{YOUR_OS}}
+Editor: {{YOUR_EDITOR}}
+Deploy: {{YOUR_DEPLOY}}
+DB: {{YOUR_DB}}
+Framework: {{YOUR_FRAMEWORK}}
+Style: {{YOUR_STYLE}}
+
+# Notes
+- Replace placeholders above with real values.
+- Keep this file updated as the stack changes.
+`;
+  const skillWritten = writeFileIfMissing(targetSkill, starter, force);
+
+  console.log("✅ solo-cto-agent initialized");
+  console.log(`- target: ${targetDir}`);
+  console.log(`- failure-catalog: ${catalogWritten ? "created" : "exists"}`);
+  console.log(`- SKILL.md: ${skillWritten ? "created" : "exists"}`);
+  console.log("\nNext:");
+  console.log("1) Open SKILL.md and replace placeholders");
+  console.log("2) Add this skill path to your agent config if needed");
+  console.log("3) Run: solo-cto-agent status");
+}
+
+function readCatalogCount(catalogPath) {
+  try {
+    const data = JSON.parse(fs.readFileSync(catalogPath, "utf8"));
+    if (Array.isArray(data.items)) return data.items.length;
+    return 0;
+  } catch {
+    return 0;
+  }
+}
+
+function getLatestCiStatus(repo, token) {
+  return new Promise((resolve) => {
+    if (!repo || !token) {
+      resolve({ status: "unavailable", conclusion: "missing token or repo" });
+      return;
+    }
+
+    const options = {
+      hostname: "api.github.com",
+      path: `/repos/${repo}/actions/runs?per_page=1`,
+      headers: {
+        "User-Agent": "solo-cto-agent",
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github+json",
+      },
+    };
+
+    https
+      .get(options, (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          try {
+            const json = JSON.parse(data);
+            const run = json.workflow_runs && json.workflow_runs[0];
+            if (!run) return resolve({ status: "unavailable", conclusion: "no runs" });
+            resolve({ status: run.status || "unknown", conclusion: run.conclusion || "unknown" });
+          } catch (e) {
+            resolve({ status: "unavailable", conclusion: "parse error" });
+          }
+        });
+      })
+      .on("error", () => resolve({ status: "unavailable", conclusion: "request failed" }));
+  });
+}
+
+async function statusCommand() {
+  const targetDir = path.join(os.homedir(), ".claude", "skills", "solo-cto-agent");
+  const skillPath = path.join(targetDir, "SKILL.md");
+  const catalogPath = path.join(targetDir, "failure-catalog.json");
+
+  const skillOk = fs.existsSync(skillPath);
+  const catalogOk = fs.existsSync(catalogPath);
+  const count = catalogOk ? readCatalogCount(catalogPath) : 0;
+
+  console.log("solo-cto-agent status");
+  console.log(`- SKILL.md: ${skillOk ? "OK" : "MISSING"}`);
+  console.log(`- failure-catalog.json: ${catalogOk ? "OK" : "MISSING"}`);
+  console.log(`- error patterns: ${count}`);
+
+  const repo = process.env.GITHUB_REPOSITORY;
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  const ci = await getLatestCiStatus(repo, token);
+  console.log(`- last CI: ${ci.status} (${ci.conclusion})`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+
+  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
+    printHelp();
+    return;
+  }
+
+  if (cmd === "init") {
+    if (args.includes("--help") || args.includes("-h")) {
+      printHelp();
+      return;
+    }
+    const force = args.includes("--force");
+    initCommand(force);
+    return;
+  }
+
+  if (cmd === "status") {
+    if (args.includes("--help") || args.includes("-h")) {
+      printHelp();
+      return;
+    }
+    await statusCommand();
+    return;
+  }
+
+  printHelp();
+  process.exit(1);
+}
+
+main();

package/docs/demo.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="900" height="420" viewBox="0 0 900 420">
+  <rect width="900" height="420" fill="#0b0f16"/>
+  <rect x="20" y="20" width="860" height="380" rx="10" fill="#111827" stroke="#1f2937"/>
+  <text x="40" y="60" fill="#93c5fd" font-family="monospace" font-size="16">npx solo-cto-agent init</text>
+  <text x="40" y="90" fill="#10b981" font-family="monospace" font-size="14">✔ initialized ~/.claude/skills/solo-cto-agent</text>
+  <text x="40" y="120" fill="#10b981" font-family="monospace" font-size="14">✔ failure-catalog.json created</text>
+  <text x="40" y="150" fill="#10b981" font-family="monospace" font-size="14">✔ SKILL.md created</text>
+
+  <text x="40" y="200" fill="#93c5fd" font-family="monospace" font-size="16">solo-cto-agent status</text>
+  <text x="40" y="230" fill="#e5e7eb" font-family="monospace" font-size="14">- SKILL.md: OK</text>
+  <text x="40" y="255" fill="#e5e7eb" font-family="monospace" font-size="14">- failure-catalog.json: OK</text>
+  <text x="40" y="280" fill="#e5e7eb" font-family="monospace" font-size="14">- error patterns: 8</text>
+  <text x="40" y="305" fill="#e5e7eb" font-family="monospace" font-size="14">- last CI: unavailable (missing token or repo)</text>
+</svg>