ineedcodes 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iNeedCodes
+
+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,161 @@
+<div align="center">
+
+<img src="docs/assets/ineed-logo.svg" alt="ineed: your terminal, now autonomous" width="640"/>
+
+# ineed
+
+[![website](https://img.shields.io/badge/web-ineed.codes-4ade80.svg)](https://ineed.codes)
+[![learn](https://img.shields.io/badge/learn-ineed.web.id-e879f9.svg)](https://ineed.web.id)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)](https://nodejs.org)
+[![platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)]()
+
+**[ineed.codes](https://ineed.codes)** (product) · **[ineed.web.id](https://ineed.web.id)** (free tutorials & AI resources) · [**Contributing**](CONTRIBUTING.md)
+
+</div>
+
+---
+
+`ineed` is a CLI-first AI agent. You describe the outcome you want in plain
+language. It figures out how: reading code, running commands, editing files,
+using Git, running tests, and proving the result with real evidence.
+
+```bash
+ineed "fix the build errors in this project"
+```
+
+<a name="why-this-project-exists"></a>
+## Why this project exists
+
+Most AI coding tools are built for people who already know Git, terminals,
+and debugging. **ineed flips that**: it is built so that *beginners can learn
+by watching an agent work*.
+
+- Every action is narrated in plain English: what it will do, why, and what
+  came out of it.
+- Nothing is hidden. You see the real commands, the real diffs, the real
+  test output. Never fabricated.
+- After finishing, the agent explains what happened and one thing worth learning.
+- If something confuses you, just ask: *"explain that more simply."*
+
+That is vibecoding: describing what you want, watching how a capable agent
+achieves it, and absorbing the workflow until you can do it yourself.
+
+<a name="quick-start"></a>
+## Quick start
+
+Requires Node.js 20+ (Windows, macOS, or Linux).
+
+```bash
+git clone https://github.com/ineedcodes/ineedcodes.git
+cd ineedcodes
+npm install
+npm run build
+npm link
+```
+
+Or, once the repository is on GitHub:
+
+```bash
+npm install -g github:ineedcodes/ineedcodes
+```
+
+`ineed` opens a **setup wizard** on first run: pick a provider, paste an API key,
+choose a model from a live list. Saved once, done forever.
+
+Any OpenAI-compatible endpoint works: OpenAI, iNeed API, OmniRoute,
+LM Studio, Ollama, vLLM, …
+
+<a name="learn-while-it-works"></a>
+## Learn while it works
+
+The whole product doubles as a teaching tool:
+
+| You type | You learn |
+|---|---|
+| `ineed` then a plain-language goal | how agents plan and verify work |
+| `/context` | how token budgets and compaction work |
+| `/plan` before `/build` | why reading before changing matters |
+| `/think high` on a hard bug | how reasoning depth changes results |
+| `/doctor` | what a healthy setup looks like |
+| `/init` | how project instructions (AGENTS.md) shape agent behavior |
+| watching the tool output | real commands, real diffs, real evidence |
+
+Explanations default to beginner-friendly. Change anytime:
+
+```bash
+/explain beginner   # more plain-English narration
+/explain balanced
+/explain terse      # for when you already know what's happening
+```
+
+> 📚 **New to AI coding?** Free tutorials on how to use AI tools, plus a
+> curated list of free AI resources, live at **[ineed.web.id](https://ineed.web.id)**.
+> No signup, no paywall.
+
+## Use it
+
+```bash
+ineed                       # interactive session here
+ineed "explain this repo"   # one-shot
+ineed --resume              # continue your last session
+```
+
+Then just talk:
+
+- *Fix the authentication bug.*
+- *Install this GitHub project and get it running.*
+- *Why is this API failing? Then fix it and prove it.*
+- *Make this README sound less AI-generated.*
+
+Slash commands are optional shortcuts (`/help`, `/model`, `/context`, `/plan`,
+`/build`, `/think`, `/memory`, `/skills`, `/permissions`, `/init`, `/doctor`,
+`/resume`, `/clear`, `/copy`, `/exit`). Plain language always works.
+
+## How it works
+
+```
+Natural language
+      ↓
+Lead Agent (understands objective, recalls ICM memory, picks skills)
+      ↓
+Iterative loop: reason → tool call → observe → adapt → verify
+      ↓
+Real execution: files, shell, git, web, MCP tools
+      ↓
+Evidence-based result: what changed, what ran, what passed
+```
+
+- **Memory**: [ICM](https://github.com/rtk-ai/icm), permanent per-project memory.
+  Conventions, solved errors, and decisions survive across sessions.
+- **Skills**: portable `SKILL.md` files. Built-ins: `boost` (isolated worktree +
+  independent verification) and `humanizer` (natural prose rewriting).
+- **Multi-agent**: the Lead Agent can spawn real sub-agents (research,
+  implementation, testing, review) in parallel.
+- **Permissions**: `ask` / `workspace` / `autonomous`. Safe in-project work
+  flows freely; destructive, remote, and secret operations need approval.
+- **Secrets**: `.env`, SSH keys, tokens are never dumped into model context.
+- **Providers**: any OpenAI-compatible API. No lock-in.
+
+## Layout
+
+```
+packages/
+  core/    tools, LLM providers, ICM adapter, permissions, context, sessions, skills
+  agent/   agent loop, lead agent, orchestrator, boost integration
+  cli/     interactive TUI, setup wizard, slash commands
+```
+
+## Contributing
+
+This project exists to teach, so contributions should keep that spirit.
+See [CONTRIBUTING.md](CONTRIBUTING.md). Good first issues: docs, beginner
+explanations, new built-in skills, provider adapters.
+
+<div align="center">
+
+**MIT Licensed.** Made for people learning to code with AI.
+
+**[ineed.codes](https://ineed.codes)** (the agent) · **[ineed.web.id](https://ineed.web.id)** (learn AI, free)
+
+</div>

package/docs/assets/ineed-logo.svg

@@ -0,0 +1,161 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1380" height="406" viewBox="0 0 1380 406">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#161b22"/>
+      <stop offset="1" stop-color="#0d1117"/>
+    </linearGradient>
+  </defs>
+  <!-- terminal window -->
+  <rect x="2" y="2" width="1376" height="402" rx="18" fill="url(#bg)" stroke="#30363d" stroke-width="2"/>
+  <!-- traffic lights -->
+  <circle cx="60" cy="28" r="7" fill="#ff5f57"/>
+  <circle cx="86" cy="28" r="7" fill="#febc2e"/>
+  <circle cx="112" cy="28" r="7" fill="#28c840"/>
+  <text x="1320" y="33" text-anchor="end" font-family="ui-monospace, Menlo, monospace" font-size="14" fill="#8b949e">~/project: ineed</text>
+
+  <!-- INEED block art -->
+    <rect x="60" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="90" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="120" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="60" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="90" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="60" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="90" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="60" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="90" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="60" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="90" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="60" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="90" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="120" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="210" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="240" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="270" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="450" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="480" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="210" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="240" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="270" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="300" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="450" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="480" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="210" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="240" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="270" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="300" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="330" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="360" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="450" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="210" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="240" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="270" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="330" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="360" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="390" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="450" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="210" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="240" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="270" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="360" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="390" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="420" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="450" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="210" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="240" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="270" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="360" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="390" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="420" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="450" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="480" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="570" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="600" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="630" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="660" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="690" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="720" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="750" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="570" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="600" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="570" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="600" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="630" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="570" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="600" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="570" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="600" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="630" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="660" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="690" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="570" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="600" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="630" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="660" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="690" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="720" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="840" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="870" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="900" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="930" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="960" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="990" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="1020" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="840" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="870" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="840" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="870" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="900" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="840" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="870" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="840" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="870" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="900" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="930" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="960" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="840" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="870" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="900" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="930" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="960" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="990" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1110" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="1140" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="1170" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="1200" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="1230" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="1260" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="1290" y="90" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="1110" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="1140" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="1260" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="1290" y="120" width="27" height="27" rx="4" fill="#4ade80"/>
+  <rect x="1110" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="1140" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="1260" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="1290" y="150" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="1110" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="1140" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="1260" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="1290" y="180" width="27" height="27" rx="4" fill="#22d3ee"/>
+  <rect x="1110" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1140" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1170" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1200" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1230" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1260" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1290" y="210" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1110" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1140" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1170" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1200" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1230" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+  <rect x="1260" y="240" width="27" height="27" rx="4" fill="#e879f9"/>
+
+  <!-- prompt line -->
+  <text x="60" y="296" font-family="ui-monospace, Menlo, monospace" font-size="26">
+    <tspan fill="#4ade80">❯</tspan><tspan fill="#e6edf3" dx="14">ineed</tspan><tspan fill="#8b949e" dx="14">"fix the build errors"</tspan><tspan fill="#4ade80">▮</tspan>
+  </text>
+
+  <!-- tagline -->
+  <text x="60" y="348" font-family="ui-monospace, Menlo, monospace" font-size="17" letter-spacing="4" fill="#6e7681">YOUR TERMINAL, NOW AUTONOMOUS</text>
+</svg>

package/docs/configuration.md

@@ -0,0 +1,71 @@
+# Configuration Reference
+
+iNeedCodes reads `~/.ineedcodes/config.json`. Every field is optional; environment variables work too.
+
+## Providers (LLM)
+
+Any OpenAI-compatible endpoint works (OpenAI, iNeed API, local servers, …):
+
+```json
+{
+  "providers": {
+    "default": { "baseUrl": "https://api.openai.com/v1", "apiKey": "sk-...", "model": "gpt-4.1-mini" },
+    "fast":    { "baseUrl": "http://localhost:11434/v1", "apiKey": "x", "model": "qwen2.5-coder", "contextLimit": 32768 }
+  },
+  "defaultProvider": "default",
+  "roleProviders": { "lead": "default", "research": "fast" }
+}
+```
+
+Environment variables: `INEEDCODES_BASE_URL`, `INEEDCODES_API_KEY`, `INEEDCODES_MODEL`.
+
+## Permissions
+
+```json
+{ "permissions": { "mode": "workspace", "allow": ["git_remote"], "deny": ["destructive"], "maxParallelAgents": 4 } }
+```
+
+- `ask`: every tool action needs approval.
+- `workspace` (default): reading, writing, and running commands inside the project
+  flow freely; outside-workspace access, remote Git pushes, destructive operations,
+  and secret access need approval.
+- `autonomous`: no interruptions (use with care).
+
+Change at runtime with `/permissions <mode>` or `ineedcodes -p <mode>`.
+
+## Memory
+
+```json
+{ "memory": { "backend": "icm" } }
+```
+
+ICM is the memory engine. Each project gets an isolated database at
+`~/.ineedcodes/projects/<project-id>/memory/icm.db`. Memories never mix
+between repositories. Set `"backend": "off"` to disable.
+
+## Web search (optional)
+
+```json
+{ "webSearch": { "provider": "brave", "apiKey": "..." } }
+```
+
+Without it, `fetch_url` still works for known URLs and the agent honestly
+reports that search is unavailable instead of pretending.
+
+## MCP servers (optional)
+
+```json
+{
+  "mcpServers": {
+    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "..." } }
+  }
+}
+```
+
+MCP tools appear in the normal registry as `mcp_<server>_<tool>` and need no
+special handling by the agent. A failing server is reported, never fatal.
+
+## Project instructions
+
+Drop an `AGENTS.md` or `.ineedcodes/instructions.md` in your repository and
+the agent applies them automatically when working there.

package/docs/skills.md

@@ -0,0 +1,58 @@
+# Skills in iNeedCodes
+
+Skills are portable instruction packs that teach the agent specialized workflows.
+A skill is a folder with a single `SKILL.md` file using YAML frontmatter.
+
+## Format
+
+```markdown
+---
+name: my-skill
+description: One sentence: when the agent should use this skill.
+version: 1.0.0          # optional
+allowed-tools:          # optional hint, informational
+  - read_file
+  - search_text
+---
+
+# My Skill
+
+Instructions the agent follows when the skill is active...
+```
+
+## Locations (priority order)
+
+1. **Project**: `<project>/.ineedcodes/skills/<name>/SKILL.md`
+2. **Project (alternate)**: `<project>/skills/<name>/SKILL.md`
+3. **Global user**: `~/.ineedcodes/skills/<name>/SKILL.md`
+4. **Built-in**: shipped with iNeedCodes (`boost`, `humanizer`)
+
+A project skill with the same name overrides the global one, which overrides
+the built-in. `/skills` shows each skill's scope so overrides are visible.
+
+## Invocation
+
+- Explicit: `/boost`, `/humanizer`, or just name the skill in a sentence.
+- Natural: *"Use boost to verify this implementation."*
+- Automatic: the Lead Agent may pick a skill when its description clearly matches the task.
+
+## Built-in: boost
+
+An advanced execution-and-verification protocol. When invoked, the agent:
+
+1. Creates an isolated Git worktree (`.ineedcodes/boost-<timestamp>`)
+2. Investigates root causes
+3. Implements changes there; your working tree stays clean
+4. Runs tests with real evidence
+5. Verifies independently
+6. Reconciles (merges) only on success, with your approval
+7. Cleans up the worktree either way
+
+A failed Boost run never merges broken changes. Good for hard debugging,
+major refactors, and regression-sensitive work. Simple tasks should not use it.
+
+## Built-in: humanizer
+
+Rewrites prose (README, docs, release notes, explanations) so it reads naturally.
+Never applied to code, JSON, YAML, commands, or technical values. Meaning and
+technical facts are always preserved.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "ineedcodes",
+  "version": "0.1.0",
+  "description": "ineed — your terminal, now autonomous. CLI-first general-purpose autonomous AI agent.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ineed": "packages/cli/dist/index.js",
+    "ineedcodes": "packages/cli/dist/index.js"
+  },
+  "files": [
+    "packages/core/dist",
+    "packages/agent/dist",
+    "packages/cli/dist",
+    "packages/core/package.json",
+    "packages/agent/package.json",
+    "packages/cli/package.json",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc -b packages/core packages/agent packages/cli",
+    "clean": "rm -rf packages/*/dist",
+    "typecheck": "tsc -b packages/core packages/agent packages/cli --force",
+    "dev": "npm run build && node packages/cli/dist/index.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "repository": {
+    "type": "git"
+  },
+  "keywords": [
+    "ai", "agent", "cli", "terminal", "autonomous", "coding", "llm"
+  ]
+}

package/packages/agent/dist/boost.d.ts

@@ -0,0 +1,34 @@
+import type { ToolRegistry, ToolContext, ToolResult } from '@ineedcodes/core';
+/**
+ * Boost integration (plan §19–20): an advanced execution and verification
+ * protocol running on top of the multi-agent runtime, in an isolated
+ * Git worktree. The user's active working tree stays clean.
+ *
+ * Lifecycle: start → investigate → implement → test → verify → reconcile | abort → cleanup
+ */
+export type BoostPhase = 'start' | 'investigate' | 'implement' | 'test' | 'verify' | 'reconcile' | 'abort' | 'cleanup';
+export interface BoostRun {
+    id: string;
+    worktreePath: string;
+    branch: string;
+    phase: BoostPhase;
+    startedAt: number;
+}
+export declare class BoostIntegration {
+    private readonly registry;
+    private readonly toolContext;
+    private readonly emit;
+    private run?;
+    constructor(registry: ToolRegistry, toolContext: ToolContext, emit: (event: import('./events.js').RuntimeEvent) => Promise<void>);
+    active(): boolean;
+    current(): BoostRun | undefined;
+    private exec;
+    start(objective: string): Promise<ToolResult>;
+    worktreeContext(): ToolContext | undefined;
+    /** Commit any uncommitted work inside the Boost worktree so it can merge. */
+    private commitWorktreeChanges;
+    reconcile(): Promise<ToolResult>;
+    abort(reason: string): Promise<ToolResult>;
+    cleanup(): Promise<ToolResult>;
+}
+export declare const BOOST_PHASES: readonly BoostPhase[];