takomi 2.0.4 → 2.0.6

package/README.md

@@ -50,6 +50,30 @@ Choose your weapons:
 
 ---
 
+## Codex Takomi Skills (No Slash Required)
+
+Takomi now supports a full skill-native protocol path in Codex:
+- Router skill: `takomi`
+- Specialist skills: `takomi-*` (migrated from non-legacy workflows)
+- Backward phrase aliases: `vibe genesis`, `vibe build`, `mode code`, and related prior names
+
+Use natural language:
+
+```text
+use takomi
+use takomi genesis
+run vibe genesis
+continue build with takomi
+```
+
+Install the Takomi protocol suite:
+
+```bash
+npx -y skills add https://github.com/JStaRFilms/VibeCode-Protocol-Suite --skill takomi
+```
+
+---
+
 ## 📦 Skill Ecosystem
 
 Think of skills as specialized team members you can summon on demand. From security audits to AI video generation — there's a skill for that.
@@ -66,7 +90,7 @@ npx -y skills add https://github.com/JStaRFilms/VibeCode-Protocol-Suite
 ### Core Essentials (Start Here)
 The non-negotiables for daily development:
 ```bash
-npx -y skills add https://github.com/JStaRFilms/VibeCode-Protocol-Suite --skill ai-sdk --skill code-review --skill component-analysis --skill nextjs-standards --skill security-audit --skill spawn-task --skill stitch --skill sync-docs
+npx -y skills add https://github.com/JStaRFilms/VibeCode-Protocol-Suite --skill takomi
 ```
 
 ### Convex Development Suite
@@ -168,7 +192,7 @@ Everything you need is in the **`.agent/`** folder.
 
 1. Copy the `.agent/` folder to your project root
 2. Your IDE automatically detects workflows and skills
-3. Invoke with slash commands (e.g., `/init_vibecode_genesis`)
+3. Invoke with natural language in Codex (e.g., `use takomi genesis`) - slash commands are optional
 
 ### What's Inside `.agent/`
 

package/assets/.agent/skills/code-review/SKILL.md

@@ -1,81 +1,34 @@
----
-name: code-review
-description: Run J-Star code review on staged changes. Analyze, fix P0/P1 issues, and iterate until clean.
----
-
-# Code Review Skill
-
-Run the J-Star Reviewer on staged changes, allowing iterative fixing of issues.
-
-## When to Use
-- Before committing code changes
-- When code quality issues are mentioned
-- As a quality gate before merging
-- When user asks to "review this code"
-
-## Quick Start
-
-### 1. Build the Brain (First Time Only)
-```bash
-jstar init
-```
-
-### 2. Stage Changes
-```bash
-git add .
-```
-
-### 3. Run Review
-```bash
-# Standard review (staged changes)
-jstar review
-
-# Retroactive (already committed)
-jstar review --last
-
-# Branch/PR review (against main)
-jstar review --pr
-```
-
-## Fix Loop Protocol
-
-1. **Read Output**: Check `.jstar/last-review.md` or console
-2. **Prioritize**: Focus on **P0_CRITICAL** and **P1_HIGH** only
-3. **Loop Strategy**:
-   - If P0/P1 found → Fix → Stage → Re-review
-   - If only P2_MEDIUM → Consider "Good Enough"
-   - **MAX LOOPS: 3** — If issues persist, stop and ask user
-
-## Handling False Positives (Headless Mode)
-
-```bash
-# Start headless session
-jstar chat --headless
-
-# List issues
-echo '{"action": "list"}' | jstar chat --headless
-
-# Debate an issue
-echo '{"action": "debate", "issueId": 0, "argument": "This is correct because..."}' | jstar chat --headless
-
-# Exit
-echo '{"action": "exit"}' | jstar chat --headless
-```
-
-## AI Fix Cycle
-```
-1. jstar review --json  →  Parse findings
-2. Apply code fixes
-3. git add .            →  Stage changes
-4. jstar init           →  Update brain (if new files added)
-5. jstar review --json  →  Verify fixes
-6. Repeat until P0/P1 = 0
-```
-
-## Headless Commands
-| Action | Parameters | Description |
-|--------|------------|-------------|
-| `list` | — | List all current issues |
-| `debate` | `issueId`, `argument` | Challenge an issue |
-| `ignore` | `issueId` | Mark issue as ignored |
-| `exit` | — | End session, get final report |
+---
+name: code-review
+description: Deprecated compatibility alias for J-Star Reviewer. Use `jstar-reviewer` for the canonical install, review, audit, and automation flows.
+---
+
+# Code Review (Deprecated)
+
+This skill is kept only for backward compatibility with older Takomi prompts and habits.
+
+Use `jstar-reviewer` as the canonical skill for:
+- installing the `jstar-reviewer` npm package
+- setting up `.jstar/`, `.env.local`, and `.gitignore`
+- running `review` and `audit`
+- using `--json` and `chat --headless` automation flows
+
+## Redirect Rule
+
+If this skill is invoked, treat it as a redirect to `jstar-reviewer`.
+
+Do not use this file as the authoritative J-Star workflow documentation.
+
+## Operational Rule
+
+`review` and `audit` are separate steps.
+
+If the user wants a serious verification pass, run both:
+1. `review` for code review findings and fix prompts
+2. `audit` for deterministic security audit findings
+
+## Canonical References
+
+- `assets/.agent/skills/jstar-reviewer/SKILL.md`
+- `assets/.agent/workflows/spawn-jstar-code-review.md`
+- `assets/.agent/workflows/review_code.md`

package/assets/.agent/skills/jstar-reviewer/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: jstar-reviewer
+description: Install, configure, and use the J-Star Reviewer npm package. Use when a user wants to set up J-Star in a repository, publish or consume the npm package, initialize the local index, run the project review flow, run the separate security audit flow, or operate J-Star through JSON/headless commands.
+---
+
+# J-Star Reviewer
+
+## When to Use
+
+Use this skill when the user wants to:
+- install J-Star from npm in any repository
+- set up `.env.local`, `.jstar/`, and `.gitignore`
+- initialize or refresh the local code index
+- run `review` and `audit` as separate required steps
+- use J-Star in automation with `--json` or `--headless`
+- validate the package repo before publishing to npm
+
+## Core Rule
+
+`review` and `audit` are separate steps.
+
+If the user is serious about a change set, run both:
+1. `review` for hybrid deterministic + LLM code review
+2. `audit` for deterministic security audit
+
+Do not present one as a substitute for the other.
+
+## Command Prefix
+
+Pick one command prefix and use it consistently for the rest of the session:
+
+- Global install: `jstar`
+- One-off npm usage: `npx jstar-reviewer`
+- Package repo development: `pnpm run`
+
+Examples below use `<cmd>` for the global or `npx` forms.
+
+## Consumer Install Flow
+
+Use this in a repository that wants to consume the published npm package.
+
+### 1. Prerequisites
+
+- Node.js 18+
+- Git repository
+- Gemini API key
+- Groq API key
+
+### 2. Install
+
+Preferred:
+
+```bash
+pnpm add -g jstar-reviewer
+```
+
+Fallback:
+
+```bash
+npm install -g jstar-reviewer
+```
+
+No global install:
+
+```bash
+npx jstar-reviewer --help
+```
+
+### 3. Set up the repo
+
+```bash
+<cmd> setup
+```
+
+This should create or update:
+- `.jstar/`
+- `.env.example`
+- `.gitignore`
+
+### 4. Create `.env.local`
+
+PowerShell:
+
+```powershell
+Copy-Item .env.example .env.local
+```
+
+POSIX shell:
+
+```bash
+cp .env.example .env.local
+```
+
+Required variables:
+
+```env
+GEMINI_API_KEY=your_gemini_key
+GROQ_API_KEY=your_groq_key
+```
+
+Optional but useful:
+
+```env
+GEMINI_EMBEDDING_MODEL=gemini-embedding-001
+REVIEW_MODEL_NAME=moonshotai/kimi-k2-instruct-0905
+```
+
+### 5. Build the local index
+
+```bash
+<cmd> init
+```
+
+If indexing fails with a Google 404 for an embedding model, use:
+
+```env
+GEMINI_EMBEDDING_MODEL=gemini-embedding-001
+```
+
+## Maintainer Flow
+
+Use this inside the `jstar-reviewer` package repo itself before publishing.
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+pnpm run index:init
+pnpm run audit --json
+```
+
+If you need to test the interactive review path inside the package repo:
+
+```bash
+git add .
+pnpm run review
+```
+
+## Required Usage Flow
+
+### Before commit or push
+
+```bash
+git add .
+<cmd> review
+<cmd> audit
+```
+
+### After the commit already exists
+
+```bash
+<cmd> review --last
+<cmd> audit --last
+```
+
+### Branch or PR scope
+
+```bash
+<cmd> review --pr
+<cmd> audit --pr
+```
+
+## Review Commands
+
+Main review targets:
+
+```bash
+<cmd> review
+<cmd> review --last
+<cmd> review --commit <hash>
+<cmd> review --range <start> <end>
+<cmd> review --pr
+<cmd> review --pr --base <branch>
+```
+
+Review outputs:
+- `.jstar/last-review.md`
+- `.jstar/session.json`
+
+## Audit Commands
+
+Main audit targets:
+
+```bash
+<cmd> audit
+<cmd> audit --path src
+<cmd> audit --last
+<cmd> audit --commit <hash>
+<cmd> audit --range <start> <end>
+<cmd> audit --pr
+<cmd> audit --pr --base <branch>
+```
+
+Audit outputs:
+- `.jstar/audit_report.md`
+- `.jstar/audit_report.json`
+
+False positives are handled with:
+- `.jstar/audit-ignore.json`
+
+## Automation Mode
+
+For machine-readable review output:
+
+```bash
+<cmd> review --json
+<cmd> audit --json
+```
+
+For issue debate:
+
+```bash
+<cmd> chat --headless
+```
+
+Headless commands:
+- `{"action":"list"}`
+- `{"action":"debate","issueId":0,"argument":"..."}`
+- `{"action":"ignore","issueId":0}`
+- `{"action":"accept","issueId":0}`
+- `{"action":"exit"}`
+
+## Decision Rules for the AI
+
+- If the repo is missing `.jstar/storage`, run `init` before `review`.
+- If the user asks for a serious verification pass, run both `review` and `audit`.
+- If the user only wants deterministic security checks, run `audit`.
+- If the user only wants code-review findings and fix prompts on a diff, run `review`.
+- If `review` says there are no staged changes, either stage files or switch to `--last`, `--range`, or `--pr`.

package/assets/.agent/skills/jstar-reviewer/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "J-Star Reviewer"
+  short_description: "Install and run J-Star review and audit"
+  default_prompt: "Use $jstar-reviewer to install J-Star in this repository and run both the review and audit flows."
+
+policy:
+  allow_implicit_invocation: true

package/assets/.agent/skills/takomi/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: takomi
+description: Unified Takomi protocol skill for Codex. Routes natural-language requests to built-in workflow playbooks in this skill folder (no slash commands required).
+---
+
+# Takomi (Unified Skill)
+
+This single skill contains the full non-legacy Takomi workflow suite.
+Use it whenever a user says "use takomi", asks for Vibe Code lifecycle execution, or references any prior workflow names.
+
+## How To Use
+- Natural language is primary. Slash commands are optional and not required.
+- Examples:
+  - `use takomi`
+  - `use takomi genesis`
+  - `run vibe genesis`
+  - `continue build with takomi`
+
+## Router Behavior
+1. Match user intent to one workflow playbook from `workflows/`.
+2. Execute that playbook's protocol.
+3. Recommend the next workflow stage after completion.
+4. Allow explicit user overrides (guided gates, not hard blocks).
+
+## Lifecycle Gates
+- Discover/Prime: `vibe-primeAgent.md`, `reverse_genesis.md`
+- Plan/Design: `vibe-genesis.md`, `vibe-design.md`, `mode-architect.md`, `mode-visionary.md`
+- Build/Continue: `vibe-build.md`, `vibe-continueBuild.md`, `mode-code.md`, `stitch.md`, `remotion-build.md`
+- Review/Finalize: `mode-review.md`, `review_code.md`, `vibe-finalize.md`, `vibe-syncDocs.md`
+- Recovery/Migration: `agent_reset.md`, `escalate.md`, `migrate.md`, `optimize-agent-context.md`, `mode-orchestrator.md`, `mode-debug.md`, `mode-ask.md`, `vibe-spawnTask.md`, `spawn-jstar-code-review.md`
+
+## Workflow Playbooks (Contained In This Skill)
+- `workflows/vibe-genesis.md`
+- `workflows/vibe-design.md`
+- `workflows/vibe-build.md`
+- `workflows/vibe-continueBuild.md`
+- `workflows/vibe-finalize.md`
+- `workflows/vibe-primeAgent.md`
+- `workflows/vibe-spawnTask.md`
+- `workflows/vibe-syncDocs.md`
+- `workflows/reverse_genesis.md`
+- `workflows/mode-orchestrator.md`
+- `workflows/mode-architect.md`
+- `workflows/mode-code.md`
+- `workflows/mode-debug.md`
+- `workflows/mode-ask.md`
+- `workflows/mode-review.md`
+- `workflows/mode-visionary.md`
+- `workflows/review_code.md`
+- `workflows/spawn-jstar-code-review.md`
+- `workflows/agent_reset.md`
+- `workflows/escalate.md`
+- `workflows/migrate.md`
+- `workflows/optimize-agent-context.md`
+- `workflows/stitch.md`
+- `workflows/remotion-build.md`
+
+## Alias Map
+See [references/migration-map.md](references/migration-map.md).

package/assets/.agent/skills/takomi/references/migration-map.md

@@ -0,0 +1,28 @@
+# Takomi Alias Map (Unified Skill)
+
+| User phrase | Internal playbook |
+|---|---|
+| `vibe genesis`, `takomi genesis` | `workflows/vibe-genesis.md` |
+| `vibe design`, `takomi design` | `workflows/vibe-design.md` |
+| `vibe build`, `takomi build` | `workflows/vibe-build.md` |
+| `continue build`, `takomi continue build` | `workflows/vibe-continueBuild.md` |
+| `finalize`, `takomi finalize` | `workflows/vibe-finalize.md` |
+| `prime agent`, `takomi prime` | `workflows/vibe-primeAgent.md` |
+| `spawn task`, `takomi spawn task` | `workflows/vibe-spawnTask.md` |
+| `sync docs`, `takomi sync docs` | `workflows/vibe-syncDocs.md` |
+| `reverse genesis` | `workflows/reverse_genesis.md` |
+| `mode orchestrator` | `workflows/mode-orchestrator.md` |
+| `mode architect` | `workflows/mode-architect.md` |
+| `mode code` | `workflows/mode-code.md` |
+| `mode debug` | `workflows/mode-debug.md` |
+| `mode ask` | `workflows/mode-ask.md` |
+| `mode review` | `workflows/mode-review.md` |
+| `mode visionary` | `workflows/mode-visionary.md` |
+| `review code` | `workflows/review_code.md` |
+| `spawn jstar code review` | `workflows/spawn-jstar-code-review.md` |
+| `agent reset` | `workflows/agent_reset.md` |
+| `escalate` | `workflows/escalate.md` |
+| `migrate` | `workflows/migrate.md` |
+| `optimize context` | `workflows/optimize-agent-context.md` |
+| `stitch` | `workflows/stitch.md` |
+| `remotion build` | `workflows/remotion-build.md` |

package/assets/.agent/skills/takomi/workflows/agent_reset.md

@@ -0,0 +1,173 @@
+---
+description: Mid-conversation reset to prevent hallucination and malformed edits in long context
+---
+
+# 🧠 Agent Reset Protocol
+
+> **TRIGGER THIS WORKFLOW** when the conversation gets long, the agent starts making mistakes, or before critical edits.
+
+---
+
+## 🛑 HARD STOP - READ THIS FIRST
+
+You are exhibiting context degradation. Before doing ANYTHING:
+
+1. **STOP THINKING. START DOING.** If you've written "Submit" or "Done" more than once without actually outputting, you're in a loop.
+2. **ONE ACTION PER TURN.** Pick ONE thing to do. Do it. Wait for feedback.
+3. **NO INTERNAL MONOLOGUE.** If you catch yourself writing "(Wait, I should...)" - STOP. That's a loop symptom.
+4. **READ BEFORE EDIT. ALWAYS.**
+
+---
+
+### 0. Re-Discover Available Skills & Workflows
+
+You may have forgotten what tools are available.
+
+**Your system prompt lists all available skills and workflows with their full absolute paths.** Check there FIRST.
+
+Fallback (if not in system prompt):
+```bash
+ls .agent/skills/ 2>/dev/null
+ls .agent/workflows/ 2>/dev/null
+```
+
+If the user's current task matches a skill (e.g., "AI SDK", "code review", "SEO", "YouTube"), **read that skill's SKILL.md immediately**.
+
+---
+
+### 0.5. Verification Protocol (TypeScript Projects)
+
+If this is a TypeScript project, run a health check:
+
+```bash
+# Check current state
+npx tsc --noEmit
+```
+
+**If this fails:** You have existing type errors. Fix them before making new changes.
+
+```bash
+# Quick verification (optional)
+python scripts/vibe-verify.py --quick 2>/dev/null
+```
+
+---
+
+### 0.6. Load Project Context
+
+If `docs/` exists, reload the project brain:
+
+```bash
+# Coding Guidelines (The Law)
+cat docs/Coding_Guidelines.md 2>/dev/null
+
+# Current work in progress
+ls docs/issues/ 2>/dev/null
+
+# Check which FR is incomplete
+grep -l "\- \[ \]" docs/issues/*.md 2>/dev/null | head -3
+```
+
+**State the current FR:** "I am working on FR-XXX: [Title]"
+
+---
+
+You are exhibiting signs of context degradation. Before continuing:
+
+### 1. Mandatory Pre-Edit Checklist
+
+```
+□ Did I READ the target file with `view_file` BEFORE editing?
+□ Did I copy the EXACT target content, including whitespace?
+□ Am I editing LESS than 50 lines at a time?
+□ Did I verify all variable names I'm using actually exist in scope?
+□ Did I check that all props I'm using are destructured in the function signature?
+```
+
+### 2. Common Hallucination Patterns to Avoid
+
+| Pattern | What Goes Wrong | Fix |
+|---------|-----------------|-----|
+| **Duplicate lines** | Pasting same useState twice | Read file first, count state declarations |
+| **Missing destructuring** | Using `onInsert` without extracting from props | Check function(props) signature matches usage |
+| **Broken JSX** | Mismatched tags, random `</Card >` | Always close tags in same edit block |
+| **Phantom variables** | Using variables that don't exist | Ctrl+F in file before using any name |
+| **Edit offset drift** | Line numbers shift after edits | Re-read file after each edit |
+
+### 3. File Edit Protocol
+
+**BEFORE ANY EDIT:**
+```
+1. view_file_outline → Understand structure
+2. view_file (exact line range) → Copy PRECISE target content
+3. Make edit with MINIMAL scope
+4. Re-check file if making another edit
+```
+
+**NEVER:**
+- Edit multiple non-contiguous sections without re-reading
+- Guess at indentation or whitespace
+- Add variables without checking they exist
+- Declare "done" without verifying lint errors are gone
+
+### 4. Panic Recovery
+
+If you made a mistake:
+
+1. **DO NOT PANIC.** Errors are fixable.
+2. **STOP making more edits.** Each edit on broken code makes it worse.
+3. **Read the current file state** with `view_file`
+4. **Identify the EXACT problem** (duplicate line? missing import? wrong scope?)
+5. **Fix ONE thing at a time**
+
+### 5. Verified Completion Protocol (The "Vibe Check")
+
+Before saying "I'm done", you MUST run this final audit:
+
+#### A. The "Anti-Slop" Syntax Check
+If the project uses TypeScript, you **MUST** run the compiler. Do not guess.
+```bash
+npx tsc --noEmit
+```
+*If this command fails, you are NOT done. Fix the errors.*
+
+#### B. The "Double Vision" Check
+Re-read the files you just edited (`view_file`).
+- [ ] Are there duplicate variable declarations? (e.g., `const prompt` defined twice?)
+- [ ] Did I accidentally paste the same code block twice?
+- [ ] Are there unused imports or missing imports?
+
+#### C. The "Task Alignment" Check
+Scroll up to the user's original request.
+- [ ] Did I actually solve the core problem?
+- [ ] Did I introduce any regressions?
+- [ ] **Lint Free?** -> `tsc` said 0 errors.
+
+Only when all 3 checks pass can you call `notify_user`.
+
+---
+
+## 📋 Quick Copy-Paste Reminder
+
+Add this to your prompts when the agent is misbehaving:
+
+```
+MANDATORY: 
+1. Use view_file BEFORE every edit to get EXACT current content
+2. Fix ONE error at a time, then re-read the file
+3. Verify all variables/props exist before using them
+4. Check @[current_problems] before declaring done
+5. DO NOT PANIC if you make errors - read, understand, fix methodically
+```
+
+---
+
+## 🎯 Why This Happens
+
+Long conversations cause:
+- **Attention drift** - Agent forgets earlier code structure
+- **Token pressure** - Summarization loses exact details
+- **Confirmation bias** - Agent "remembers" code that doesn't exist
+- **Panic loops** - Error triggers more hasty edits
+
+**The fix is always: SLOW DOWN, READ FIRST, EDIT SMALL.**