@lenardangeloolajay/len-toolkit 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Len
+
+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,209 @@
+# Len's Toolkit
+
+![Len's Toolkit](assets/ChatGPT%20Image%20Sep%2020,%202026,%2009_45_22%20PM.png)
+
+> [!NOTE]
+> **Collection Disclaimer and Attribution:**
+> This repository is strictly a curated collection of tools, skills, and engineering rulesets sourced from experienced engineers across the software industry.
+> I am not the author of these files, and I do not claim 100% ownership over them.
+> I gathered and adapted these tools from other people to build a streamlined AI coding workflow, and I credit them fully for their work.
+
+This repository contains my personal guidelines, rulesets, and skills for AI pair programming.
+Feel free to copy whatever you want and create PRs!
+Technically this is a disciplined ruleset designed to help build solid, high quality code instead of unverified slop.
+
+A personal, dependency-free toolkit for Len's GPT-to-Antigravity workflow.
+GPT explores the product and defines architecture with Len.
+Len approves the specs and plan.
+Gemini implements approved phases with checks and local commits.
+
+## Start a project session
+
+Run this from the project directory once this revision has been published:
+
+```powershell
+npx @lenardangeloolajay/len-toolkit start
+```
+
+This checkout has not been published by this change.
+To use the current local checkout from any project now, substitute its absolute path in this one-command equivalent:
+
+```powershell
+npm exec --offline --package="C:\path\to\Len's_Toolkit" -- len-toolkit start
+```
+
+The local-package form was exercised with npm in a temporary project on Windows.
+It does not require a global install.
+Then launch your usual Antigravity CLI:
+
+```powershell
+agi
+```
+
+Tell the receiving agent: "Read project AGENTS.md and HANDOFF.md, follow their approved references, and execute the approved plan."
+If the project has no approved handoff yet, work with GPT on the specs first.
+Automatic Antigravity instruction discovery has not been verified here; explicitly point it to the files.
+
+## What startup does
+
+- Initializes Git only when there is no enclosing repository, reporting the branch and existing edits.
+- Installs missing personal rules, 24 skills, reusable document templates, and basic development configs.
+- Preserves existing files and reports differences with paths to the proposed versions.
+- Checks whether Git can resolve author and committer identity without changing your configuration.
+- Reports whether the index, handoff, and root plan exist, leaving content and approval review to the agent.
+
+Startup does not approve work, create a second spec tree, launch an agent, stage files, commit, or push.
+It refuses `--force` and `--global`; use the legacy commands only when their broader behavior is intended.
+A successful exit means setup checks finished, not that differences are resolved or the project is approved for implementation.
+A failed setup may have created a repository or installed some missing files before the error; address the reported issue and rerun safely.
+Existing custom instructions require review, not an automatic overwrite disguised as an upgrade.
+
+## The personal workflow
+
+1. Explore the whole product with GPT in focused question rounds, including proposed defaults and unresolved requirements.
+2. Settle planned features, main user flows, shared data, boundaries, architecture, and major constraints.
+3. Approve the product baseline and architecture in chat.
+4. Detail one feature's observable requirements, then its implementation plan; approve both in chat.
+5. Maintain one current handoff with exact approved revisions, allowed phases, progress, checks, attempts, and next action.
+6. Gemini implements each approved phase, verifies it, updates the records, reviews the staged diff, and commits only related changes.
+7. Gemini continues automatically until the last approved phase or a real blocker.
+
+A phase is complete only after passing required checks and a successful commit.
+Interrupted or failing work remains uncommitted.
+For the same unresolved problem, Gemini gets three unsuccessful fix-and-check attempts after the initial observed failure, then reports a blocker without resetting the count on resume.
+Missing decisions, unavailable access or hardware, and necessary architecture changes block affected work immediately.
+Gemini can report a disagreement but cannot silently replace approved architecture or add features.
+Len's approval applies to specific revisions, not future substantive changes.
+
+## Documents that stay organized
+
+```text
+project/
+  AGENTS.md                         Shared personal workflow
+  GEMINI.md                         Gemini entry point
+  HANDOFF.md                        One current handoff
+  IMPLEMENTATION_PLAN.md            Optional pointer to the active plan
+  .agents/
+    skills/                         Spec, Council, plan, and Ponytail suite
+    templates/docs/                 Reusable templates, not active specs
+  docs/
+    SPEC_INDEX.md                   Current documents, revisions, and status
+    product/
+      OVERVIEW.md
+      ARCHITECTURE.md
+      DATA_MODEL.md
+      CONSTRAINTS.md
+    features/FEAT-001-name.md        Behavior and acceptance criteria
+    plans/FEAT-001-implementation.md Tasks, checks, and phase progress
+    evidence/FEAT-001-verification.md
+    archive/                        Superseded documents with replacement links
+```
+
+Create categories only when needed and adopt an existing project convention rather than duplicating it.
+Search the index and current specs before creating a file.
+Refinements update the existing feature spec; superseded documents move to the archive with replacement links and updated references.
+Active filenames are stable, while creation and substantive-update timestamps inside documents use ISO 8601 with `+08:00`.
+Requirements have stable IDs, and plans and evidence reference them.
+Specs describe behavior; plans contain task checkboxes and commands.
+
+Use [the fictional Flutter handoff](templates/examples/flutter-handoff/docs/SPEC_INDEX.md) to inspect a complete example.
+Its approvals, implementation, and verification are deliberately pending.
+[Inspection exercises](templates/examples/flutter-handoff/EXERCISES.md) cover reuse, supersession, interruption, retries, and evidence boundaries.
+No fictional project has been tested on an emulator or device.
+
+## Skills and templates
+
+Len's Toolkit includes 24 curated skills across core workflow, security, and software engineering book principles:
+
+### Core Workflow and Optimization Skills
+
+- `spec`: product discovery, organized requirements, document reuse, and revision approval.
+- `council`: consequential architecture trade-offs and failure modes before approval.
+- `implementation-plan`: approved phases, verification, commits, and recovery.
+- `ponytail`: reuse, standard-library-first implementation, and minimal necessary code.
+- `ponytail-review` and `ponytail-audit`: complexity findings without automatic fixes.
+- `ponytail-debt`: recorded deliberate shortcuts.
+- `ponytail-gain`: attributable evidence only; no unsupported savings figures.
+- `ponytail-help`: the Ponytail reference card.
+- `security-audit`: security guidance, vulnerability review, and structured audit harness.
+
+### Software Engineering Book Skills
+
+Distilled rules from classic software engineering literature, adapted from [Maciej Ciemborowicz's agent-rules-books](https://github.com/ciembor/agent-rules-books):
+
+- `a-philosophy-of-software-design`: complexity reduction and deep module boundaries (John Ousterhout).
+- `clean-architecture`: separation of business policy from frameworks and details (Robert C. Martin).
+- `clean-code`: readability, naming, small functions, and clean code hygiene (Robert C. Martin).
+- `code-complete`: software construction, routine design, and defensive programming (Steve McConnell).
+- `designing-data-intensive-applications`: reliability, scalability, and consistency in data systems (Martin Kleppmann).
+- `domain-driven-design`: domain modeling, bounded contexts, and ubiquitous language (Eric Evans).
+- `domain-driven-design-distilled`: lightweight domain modeling and subdomains (Vaughn Vernon).
+- `implementing-domain-driven-design`: tactical DDD patterns, aggregates, and domain events (Vaughn Vernon).
+- `patterns-of-enterprise-application-architecture`: enterprise layers, repositories, and mappers (Martin Fowler).
+- `refactoring`: systematic code refactoring and mechanics (Martin Fowler).
+- `refactoring-guru`: code smell diagnosis and refactoring technique catalogs (Refactoring.Guru).
+- `release-it`: production stability, circuit breakers, and resilience (Michael T. Nygard).
+- `the-pragmatic-programmer`: pragmatic judgment, orthogonality, and DRY principles (David Thomas and Andrew Hunt).
+- `working-effectively-with-legacy-code`: safely modifying legacy systems with characterization tests and seams (Michael Feathers).
+
+The shared policy lives in [the AGENTS template](templates/rules/AGENTS.md).
+The [plan template](templates/docs/IMPLEMENTATION_PLAN.md) is used by both CLI plan generation and agent guidance.
+Templates contain unresolved fields until the agent inspects the actual project; they are not ready-to-execute commands.
+
+## Evidence, not promises
+
+Record the requirement, actual command or scenario, environment, result, timestamp, and limitations.
+Attach meaningful UI screenshots when available.
+Emulator results establish emulator behavior only; Len performs physical-device checks.
+Keep hardware-bench and field validation separate, with unrun checks explicitly pending.
+Implementation, simulation, or an attractive spec does not prove effectiveness in the intended environment.
+
+## Compatibility commands
+
+```powershell
+npx @lenardangeloolajay/len-toolkit --help
+npx @lenardangeloolajay/len-toolkit skills
+npx @lenardangeloolajay/len-toolkit rules
+npx @lenardangeloolajay/len-toolkit plan "Feature name"
+npx @lenardangeloolajay/len-toolkit --yes
+npx @lenardangeloolajay/len-toolkit skills --global
+```
+
+The legacy default remains an interactive installer.
+Local skill installation also supplies document templates.
+The legacy global skill destination remains `~/.gemini/config/skills/`; it is not the recommended personal setup and does not replace local startup.
+The `plan` command writes a draft root `IMPLEMENTATION_PLAN.md` and preserves an existing file by default.
+For categorized feature plans, use the spec/plan workflow and a root pointer instead of generating a second active plan.
+Legacy `--force` overwrites existing selected files, including `.gitignore` and a root plan; it is never used by `start`.
+Cursor-related compatibility files remain available but are not installed by personal startup.
+
+## Local verification
+
+The package advertises Node 18 or newer and uses no npm dependencies.
+This change was exercised on Windows with Node 24.14.0; other supported runtime versions remain unverified here.
+
+```powershell
+npm test
+node --check bin/cli.js
+node --check src/installer.js
+npm pack --dry-run --ignore-scripts
+```
+
+The automated suite exercises file preservation, CLI behavior, startup failure cases, enclosing repositories, and shared plan rendering.
+Workflow exercises are instruction inspections, not proof that Gemini will always comply.
+Publishing or pushing remains a separate explicit action.
+
+## License and attribution
+
+[MIT](LICENSE).
+
+This repository is strictly a curated collection of tools and guidelines.
+I am not the author of these files, and I do not claim 100% ownership over them.
+I gathered these tools from other experienced engineers and credit them fully for their contributions:
+
+- Ponytail derives from [Dietrich Gebert's Ponytail](https://github.com/DietrichGebert/ponytail).
+- Council is inspired by [hex/claude-council](https://github.com/hex/claude-council).
+- Security audit skill derives from [Cloudflare's security-audit-skill](https://github.com/cloudflare/security-audit-skill).
+- Software engineering book skills derive from [Maciej Ciemborowicz's agent-rules-books](https://github.com/ciembor/agent-rules-books).
+- Book summaries and architectural patterns are based on the published works of John Ousterhout, Robert C. Martin, Steve McConnell, Martin Kleppmann, Eric Evans, Vaughn Vernon, Martin Fowler, Michael T. Nygard, David Thomas, Andrew Hunt, Michael Feathers, and the authors of Refactoring.Guru.
+All upstream authors retain copyright to their respective original works.

package/bin/cli.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+const [major] = process.versions.node.split('.').map(Number);
+if (major < 18) {
+  console.error('len-toolkit requires Node.js >= 18.0.0. Current: ' + process.version);
+  process.exit(1);
+}
+
+import readline from 'node:readline';
+import process from 'node:process';
+import { readFileSync } from 'node:fs';
+import {
+  installSkills,
+  installRules,
+  installConfigs,
+  createPlanTemplate,
+  startWorkspace
+} from '../src/installer.js';
+
+const { version: VERSION } = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf-8')
+);
+
+const STARTUP_BANNER = `LEN'S TOOLKIT // ASU DEVELOPER'S GUILD
+ ───────────────────────────────────────────────────────────────────────────────────────────────
+
+ ██╗     ███████╗███╗   ██╗███████╗    ████████╗ ██████╗  ██████╗ ██╗     ██╗  ██╗██╗████████╗
+ ██║     ██╔════╝████╗  ██║██╔════╝    ╚══██╔══╝██╔═══██╗██╔═══██╗██║     ██║ ██╔╝██║╚══██╔══╝
+ ██║     █████╗  ██╔██╗ ██║███████╗       ██║   ██║   ██║██║   ██║██║     █████╔╝ ██║   ██║
+ ██║     ██╔══╝  ██║╚██╗██║╚════██║       ██║   ██║   ██║██║   ██║██║     ██╔═██╗ ██║   ██║
+ ███████╗███████╗██║ ╚████║███████║       ██║   ╚██████╔╝╚██████╔╝███████╗██║  ██╗██║   ██║
+ ╚══════╝╚══════╝╚═╝  ╚═══╝╚══════╝       ╚═╝    ╚═════╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝   ╚═╝
+
+                                   LEARN ・ BUILD ・ SHIP
+
+ ─────────────────┐
+   LEN / 2026     │   PERSONAL DEVELOPMENT TOOLKIT
+                  └────────────────────────────────────────────────────────────────────────────`;
+
+function getBanner() {
+  return `\n\x1b[1m\x1b[36m${STARTUP_BANNER}\x1b[0m\n`;
+}
+
+function printBanner() {
+  console.log(getBanner());
+}
+
+function printHelp() {
+  printBanner();
+  console.log(`
+\x1b[1mUSAGE:\x1b[0m
+  npx len-toolkit [command] [options]
+
+\x1b[1mCOMMANDS:\x1b[0m
+  start                    Prepare local GPT/Antigravity workflow safely (recommended)
+  init                     Initialize vibe coding environment in current project (default)
+  plan [name]              Generate a phased IMPLEMENTATION_PLAN.md file
+  skills                   Install only the skills library (.agents/skills/)
+  rules                    Install only the agent rules (GEMINI.md, AGENTS.md, .cursorrules)
+
+\x1b[1mOPTIONS:\x1b[0m
+  -y, --yes                Skip interactive prompts and install all components
+  -g, --global             Install skills globally to ~/.gemini/config/skills/
+  -f, --force              Overwrite existing files
+  -h, --help               Show this help message
+  -v, --version            Display current version
+
+\x1b[1mSKILLS INCLUDED:\x1b[0m
+  spec                    Product discovery and organized feature specifications
+  🏛️  council               Multi-perspective ideation & debate (Devil, Simplicity, Security, DX)
+  📋 implementation-plan   Approved execution with checks, phase commits & bounded retries
+  ✂️  ponytail (suite)      Anti-bloat ladder, ponytail-audit, ponytail-debt, ponytail-review
+  🛡️  security-audit        Security guidance, vulnerability review & structured audit harness
+  📚 books (14 skills)     Classic SWE principles (Clean Code/Arch, Refactoring, DDD, Reliability)
+`);
+}
+
+async function askQuestion(rl, query) {
+  return new Promise((resolve) => rl.question(query, resolve));
+}
+
+async function runInteractive(targetDir, flags) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  let completed = false;
+  rl.on('close', () => {
+    if (!completed) {
+      console.log('\n\nSetup cancelled.');
+      process.exit(0);
+    }
+  });
+
+  printBanner();
+  console.log(`Target directory: \x1b[33m${targetDir}\x1b[0m\n`);
+
+  const installAll = await askQuestion(rl, 'Initialize full toolkit (Skills + Rules + Dev configs)? [Y/n]: ');
+  const shouldInstallAll = installAll.trim().toLowerCase() !== 'n';
+
+  let doSkills = shouldInstallAll;
+  let doRules = shouldInstallAll;
+  let doConfigs = shouldInstallAll;
+
+  if (!shouldInstallAll) {
+    const ansSkills = await askQuestion(rl, 'Install Skills library (council, ponytail, security-audit, book skills)? [Y/n]: ');
+    doSkills = ansSkills.trim().toLowerCase() !== 'n';
+
+    const ansRules = await askQuestion(rl, 'Install Agent Rules (GEMINI.md, AGENTS.md)? [Y/n]: ');
+    doRules = ansRules.trim().toLowerCase() !== 'n';
+
+    const ansConfigs = await askQuestion(rl, 'Install Dev Configs (.editorconfig, .gitignore)? [Y/n]: ');
+    doConfigs = ansConfigs.trim().toLowerCase() !== 'n';
+  }
+
+  const globalOpt = await askQuestion(rl, 'Also install skills globally to ~/.gemini/config/skills/? [y/N]: ');
+  const doGlobal = globalOpt.trim().toLowerCase() === 'y';
+
+  completed = true;
+  rl.close();
+
+  console.log('\n\x1b[32mApplying configuration...\x1b[0m');
+
+  if (doSkills) {
+    const dest = installSkills(targetDir, false, flags.force);
+    console.log(`  ✓ Installed skills to ${dest}`);
+  }
+
+  if (doGlobal) {
+    const globalDest = installSkills(targetDir, true, flags.force);
+    console.log(`  ✓ Installed global skills to ${globalDest}`);
+  }
+
+  if (doRules) {
+    const rules = installRules(targetDir, flags.force);
+    console.log(`  ✓ Installed agent rules: ${rules.join(', ')}`);
+  }
+
+  if (doConfigs) {
+    const configs = installConfigs(targetDir, flags.force);
+    console.log(`  ✓ Installed dev configs: ${configs.join(', ')}`);
+  }
+
+  console.log(`
+\x1b[32m🎉 Toolkit setup complete!\x1b[0m
+Your environment is now primed with:
+  • \x1b[36m/council\x1b[0m               for stress-testing architecture and ideation
+  • \x1b[36m/plan\x1b[0m                  for phased IMPLEMENTATION_PLAN.md with test gates & commits
+  • \x1b[36m/ponytail\x1b[0m              for minimal, zero-bloat standard-library execution
+  • \x1b[36msecurity-audit\x1b[0m         for defensive vulnerability hunting & security reviews
+  • \x1b[36mbooks (14 skills)\x1b[0m      for clean code, refactoring, DDD, architecture & reliability
+`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const targetDir = process.cwd();
+
+  const flags = {
+    yes: args.includes('-y') || args.includes('--yes'),
+    global: args.includes('-g') || args.includes('--global'),
+    force: args.includes('-f') || args.includes('--force'),
+    help: args.includes('-h') || args.includes('--help'),
+    version: args.includes('-v') || args.includes('--version'),
+  };
+
+  if (flags.help) {
+    printHelp();
+    return;
+  }
+
+  if (flags.version) {
+    console.log(`len-toolkit v${VERSION}`);
+    return;
+  }
+
+  const command = args[0] && !args[0].startsWith('-') ? args[0] : 'init';
+
+  if (command === 'start') {
+    if (args.slice(1).some((arg) => !['-y', '--yes'].includes(arg))) {
+      throw new Error('start is local and preserves existing files. Use: len-toolkit start (optionally --yes).');
+    }
+    printBanner();
+    const result = startWorkspace(targetDir);
+    console.log(`${result.initialized ? 'Initialized' : 'Using'} Git repository: ${result.repository}`);
+    console.log(`Branch: ${result.branch}`);
+    console.log(`Installed ${result.installed.length} missing files.`);
+    for (const difference of result.differences) {
+      console.log(`REVIEW: ${difference.path} differs; preserved. Proposed version: ${difference.proposed}`);
+    }
+    for (const warning of result.identityWarnings) console.log(`COMMIT CHECK: ${warning}`);
+    console.log(`Working tree (preserve unrelated edits):\n${result.changes || '(clean)'}`);
+    for (const doc of result.documents) {
+      console.log(`DOCUMENT REVIEW: ${doc.path}: ${doc.exists ? 'present; agent must verify currency and approval' : 'missing; inventory existing specs before creating it'}`);
+    }
+    console.log('Setup check complete. This does not approve implementation or verify Antigravity discovery.');
+    console.log('Review differences and specs with GPT, then launch agi and point it to the approved HANDOFF.md.');
+    return;
+  }
+
+  if (command === 'plan') {
+    const featureName = args.slice(1).find((arg) => !arg.startsWith('-')) || 'New Feature';
+    const result = createPlanTemplate(targetDir, featureName, flags.force);
+    if (result.created) {
+      console.log(`\x1b[32m✓ Created ${result.path}\x1b[0m`);
+    } else {
+      console.log(`\x1b[33m! ${result.path} already exists. Left untouched.\x1b[0m`);
+    }
+    return;
+  }
+
+  if (command === 'skills') {
+    const dest = installSkills(targetDir, flags.global, flags.force);
+    console.log(`\x1b[32m✓ Installed skills to ${dest}\x1b[0m`);
+    return;
+  }
+
+  if (command === 'rules') {
+    const rules = installRules(targetDir, flags.force);
+    console.log(`\x1b[32m✓ Installed agent rules: ${rules.join(', ')}\x1b[0m`);
+    return;
+  }
+
+  if (flags.yes) {
+    printBanner();
+    console.log(`Target: \x1b[33m${targetDir}\x1b[0m`);
+    const dest = installSkills(targetDir, flags.global, flags.force);
+    console.log(`  ✓ Installed skills to ${dest}`);
+    const rules = installRules(targetDir, flags.force);
+    console.log(`  ✓ Installed agent rules: ${rules.join(', ')}`);
+    const configs = installConfigs(targetDir, flags.force);
+    console.log(`  ✓ Installed dev configs: ${configs.join(', ')}`);
+    console.log('\n\x1b[32m✓ Vibe coding environment initialized successfully!\x1b[0m');
+    return;
+  }
+
+  await runInteractive(targetDir, flags);
+}
+
+main().catch((err) => {
+  console.error('\x1b[31mError running len-toolkit:\x1b[0m', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@lenardangeloolajay/len-toolkit",
+  "version": "1.1.0",
+  "description": "Len's personal GPT-to-Antigravity workflow: organized specs, explicit approval, safe startup, verified phase commits, and bounded recovery.",
+  "type": "module",
+  "bin": {
+    "len-toolkit": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node ./bin/cli.js",
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "keywords": [
+    "antigravity",
+    "ai-agent",
+    "vibe-coding",
+    "skills",
+    "ponytail",
+    "claude-council",
+    "scaffold",
+    "cli"
+  ],
+  "author": "Len",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}