takomi 2.0.4 → 2.0.6

package/assets/.agent/skills/takomi/workflows/vibe-syncDocs.md

@@ -0,0 +1,90 @@
+---
+description: Document recent code changes by reviewing and updating feature docs
+---
+
+# Documentation Sync Workflow
+
+This workflow updates `docs/features/` after major code changes.
+
+## Prerequisites
+- You have just completed a code change (feature, fix, refactor)
+- You know which files were modified
+
+## Steps
+
+### 1. Identify Changed Components
+List the main files that were modified in the recent change. Focus on:
+- `src/main/` (backend logic)
+- `src/renderer/` (UI components)
+- `src/shared/` (types, constants)
+
+### 2. List Existing Feature Docs
+// turbo
+```bash
+ls docs/features/
+```
+
+### 3. Read Doc Names and Summaries
+For each doc, read the first 20 lines to understand its scope:
+// turbo
+```bash
+head -20 docs/features/*.md
+```
+
+### 4. Determine Action
+For each changed component, decide:
+- **UPDATE** an existing doc if the feature already has documentation
+- **CREATE** a new doc if this is a new feature or subsystem
+- **SKIP** if the change is minor and already covered
+
+### 5. Documentation Standards
+Each feature doc should follow this template:
+
+```markdown
+# Feature Name
+
+## Overview
+One paragraph explaining what this feature does.
+
+## Architecture
+- **Service/File:** `src/main/path/to/file.ts`
+- **Dependencies:** List key dependencies
+
+## Key Components
+
+### Component 1
+Explanation...
+
+### Component 2
+Explanation...
+
+## Data Flow (optional)
+Use mermaid diagrams for complex flows:
+```mermaid
+flowchart LR
+    A --> B --> C
+```
+
+## Configuration (if applicable)
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| ...     | ...  | ...     | ...         |
+
+## Hotfixes / Changelog (optional)
+Document significant bug fixes with dates:
+### Hotfix YYYY-MM-DD: Brief Title
+- **Problem:** What was broken
+- **Solution:** How it was fixed
+```
+
+### 6. Write Updates
+- If **UPDATE**: Use `view_file` to read the existing doc, then `replace_file_content` to add/modify sections.
+- If **CREATE**: Use `write_to_file` to create a new doc following the template above.
+
+### 7. Verify Links
+Ensure any file paths mentioned in docs are correct (use backticks for paths).
+
+### 8. Summary
+After completion, list what was updated/created:
+- Updated: `docs/features/foo.md` (added XYZ section)
+- Created: `docs/features/bar.md` (new feature doc)

package/assets/.agent/workflows/review_code.md

@@ -1,133 +1,96 @@
----
-description: Run the J-Star Code Reviewer loop to analyze and fix code quality issues.
----
-
-# J-Star Code Review Workflow
-
-This workflow executes the J-Star Reviewer on staged changes, allowing the agent to iteratively fix issues.
-
-## 1. Build the Brain (Required once)
-If you haven't indexed the project yet, or if major files have changed, run:
-// turbo
-```bash
-jstar init
-```
-
-## 2. Stage Current Changes
-Ensure all recent changes are staged so the reviewer can see them.
-// turbo
-```bash
-git add .
-```
-
-## 3. Run Reviewer
-Execute the review pipeline.
-
-### Standard Review (Staged Changes)
-```bash
-jstar review
-```
-*Use this when changes are staged but not yet committed.*
-
-### Retroactive Review (Oops Mode)
-If you already committed changes but forgot to review:
-```bash
-jstar review --last
-```
-*Equivalent to checking the last commit `HEAD~1..HEAD`.*
-
-### Branch/PR Review
-If working on a feature branch, check against main:
-```bash
-jstar review --pr
-```
-*Equivalent to `git diff main...HEAD`. Use this for full feature verification.*
-
-## 4. Analyze and Fix
-**Agent Instructions:**
-1.  **Read the Output**: Check `.jstar/last-review.md` or the console summary.
-2.  **Prioritize**: Focus *only* on **P0_CRITICAL** and **P1_HIGH** issues first.
-3.  **Looping Strategy**:
-    - **IF** P0/P1 issues are found:
-        - Apply fixes to the code.
-        - Stage changes: `git add .`
-        - (Optional) Re-index if you added new files: `jstar init`
-        - Restart this workflow (Stage -> Review).
-    - **IF** only P2_MEDIUM issues remain:
-        - You may fix them if they are quick/obvious.
-        - Otherwise, consider the code "Good Enough" and stop.
-    - **MAX LOOPS**: 3. Do not run this cycle more than 3 times. If issues persist, stop and ask the user.
-
-## 5. Handling False Positives (Debate Mode)
-
-If the reviewer flags correct code as an issue (e.g., security false positives), use **Headless Chat** to resolve it.
-
-**Protocol:**
-1. **Start Session:**
-   Use the `run_command` tool to start the background process:
-   ```bash
-   jstar chat --headless
-   ```
-   *Note: Capture the `CommandId` returned by this tool.*
-
-2. **List Issues (Get IDs):**
-   Use `send_command_input` with the `CommandId`:
-   ```json
-   {"action": "list"}
-   ```
-   *Wait for output. Identify the numeric `id` of the issue you want to challenge.*
-
-3. **Debate:**
-   Use `send_command_input` to explain why it's a false positive:
-   ```json
-   {"action": "debate", "issueId": 0, "argument": "This is correct because..."}
-   ```
-   *Use the integer `id` from step 2.*
-
-4. **Verify Result:**
-   Check the output for `"status": "resolved"` and `"verdict": "LGTM"`.
-
-5. **Exit:**
-   Terminate the session cleanly:
-   ```json
-   {"action": "exit"}
-   ```
-
----
-
-## AI Agent Mode (Headless)
-
-For programmatic interaction without TUI navigation, use headless mode.
-
-### JSON Review (One-Shot)
-Get findings as JSON for parsing:
-// turbo
-```bash
-jstar review --json > .jstar/report.json
-```
-
-### Headless Chat (Interactive Protocol)
-For debating specific issues via stdin/stdout:
-```bash
-echo '{"action": "list"}' | jstar chat --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 |
-
-See [Headless Mode Docs](../docs/features/headless-mode.md) for full protocol.
-
-### 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
-```
+---
+description: Run the up-to-date J-Star review and audit loop for a change set.
+---
+
+# J-Star Review Workflow
+
+Use this workflow when the repository already has J-Star installed and you need to verify a change set.
+
+## Core Rule
+
+`review` and `audit` are separate steps.
+
+For a serious verification pass, run both.
+
+## 1. Build the Local Index
+
+If the repository is missing `.jstar/storage`, or if major files were added, run:
+
+```bash
+jstar init
+```
+
+## 2. Choose the Scope
+
+### Staged changes
+
+```bash
+git add .
+jstar review
+jstar audit
+```
+
+### Last commit
+
+```bash
+jstar review --last
+jstar audit --last
+```
+
+### Branch or PR scope
+
+```bash
+jstar review --pr
+jstar audit --pr
+```
+
+## 3. Read the Outputs
+
+Review outputs:
+- `.jstar/last-review.md`
+- `.jstar/session.json`
+
+Audit outputs:
+- `.jstar/audit_report.md`
+- `.jstar/audit_report.json`
+
+## 4. Fix Loop
+
+Agent instructions:
+1. Read both the review and audit outputs.
+2. Prioritize review `P0_CRITICAL` and `P1_HIGH` issues first.
+3. Prioritize audit `CRITICAL` and `HIGH` findings first.
+4. Apply fixes.
+5. Stage changes with `git add .`.
+6. Re-run both `review` and `audit` for the same scope.
+7. If only lower-priority review issues remain, stop when the remaining work is not worth another loop.
+8. Maximum loops: 3. If issues persist, stop and ask the user.
+
+## 5. False Positives and Debate
+
+For review findings that need challenge or adjudication:
+
+```bash
+jstar chat --headless
+```
+
+Headless commands:
+- `{"action":"list"}`
+- `{"action":"debate","issueId":0,"argument":"..."}`
+- `{"action":"ignore","issueId":0}`
+- `{"action":"accept","issueId":0}`
+- `{"action":"exit"}`
+
+For known deterministic audit false positives, use:
+- `.jstar/audit-ignore.json`
+
+## 6. Automation Mode
+
+Machine-readable review output:
+
+```bash
+jstar review --json > .jstar/last-review.json
+jstar audit --json > .jstar/audit_report.json
+```
+
+Use `review --json` and `audit --json` for automation. Do not rely on `review --headless`.

package/assets/.agent/workflows/spawn-jstar-code-review.md

@@ -1,121 +1,161 @@
----
-description: Spawn J Star Code Review bot into the current repository
----
-
-# /spawn-jstar - Add J Star Reviewer v2 to Any Project
-
-Works with **any programming language** — TypeScript, Python, Rust, Go, etc.
-
-## Prerequisites
-- Node.js 18+ installed on your machine
-
-## Steps
-
-### 1. Install the CLI Globally (One Time) use pnpm by default else revert to npm
-// turbo
-```bash
-pnpm install -g jstar-reviewer
-```
-
-### 2. Run your First Command
-// turbo
-```bash
-jstar setup
-```
-*(Or simply run `jstar review` if you already have your keys ready)*
-
-This **auto-creates** (or updates):
-- `.jstar/` directory
-- `.env.example` with required variables
-- `.gitignore` (appends `.jstar/` and `.env.local`)
-
-
-### 3. Configure Environment Variables
-```bash
-cp .env.example .env.local
-```
-
-Edit `.env.local` and add your API keys:
-```env
-GEMINI_API_KEY=your_gemini_api_key_here
-GROQ_API_KEY=your_groq_api_key_here
-```
-
-**Where to get keys:**
-- Google API Key: [Google AI Studio](https://aistudio.google.com/apikey)
-- Groq API Key: [console.groq.com](https://console.groq.com)
-
-### 4. Index Your Codebase (Build the Brain)
-```bash
-jstar init
-```
-
-This scans your codebase and creates embeddings for context-aware reviews.
-
-### 5. (Optional) Create Rules File
-Create `.jstar/rules.md` with your project-specific coding guidelines:
-
-```markdown
-# Project Coding Rules
-
-## General
-- Follow PEP 8 (Python) / Google Style Guide
-- Add docstrings to all public functions
-
-
-
-## Security  
-- Never log sensitive data
-- Validate all user inputs
-```
-
-### 6. Understanding Review Modes
-Before running a review, understand the available modes:
-
-| Mode | Command | Best For |
-| :--- | :--- | :--- |
-| **Standard** | `jstar review` | checking staged changes *before* committing. |
-| **Retroactive** | `jstar review --last` | checking the *last commit* (if you forgot to review). |
-| **Pull Request** | `jstar review --pr` | checking an entire feature branch against `main`. |
-
-### 7. Run Your First Review
-
-**Agent Instruction:** Ask the user: *"Would you like to run the review yourself, or should I run a headless check for you?"*
-
-#### Option A: User Runs It (Recommended)
-The user runs the interactive TUI command in their terminal:
-```bash
-jstar review
-```
-
-#### Option B: Agent Runs It (Headless)
-If the user asks YOU to do it, use the headless flag to avoid hanging:
-// turbo
-```bash
-jstar review --headless
-```
-*(This outputs JSON-formatted results that you can parse)*
-
-The dashboard will be saved to `.jstar/last-review.md`.
-
-## Done! 🎉
-
-**CLI Commands:**
-| Command | Description |
-|---------|-------------|
-| `jstar setup` | Create config files in current project |
-| `jstar init` | Index codebase (after major changes) |
-| `jstar review` | Review staged changes (Default) |
-| `jstar review --last` | Review last commit (Retroactive) |
-| `jstar review --pr` | Review branch against main (PR Mode) |
-
-**Output:**
-- Console: Quick summary with severity counts
-- `.jstar/last-review.md`: Full dashboard with fix prompts
-
-## Alternative: Without Global Install
-
-If you don't want to install globally:
-```bash
-npx jstar-reviewer review
-```
+---
+description: Install J-Star Reviewer in the current repository and set up the up-to-date review and audit flows.
+---
+
+# /spawn-jstar - Install J-Star Reviewer in This Repository
+
+Use this workflow to install the `jstar-reviewer` npm package and wire the repository for both code review and security audit.
+
+## Core Rule
+
+`review` and `audit` are separate steps.
+
+For a serious verification pass, run both. Do not present one as a substitute for the other.
+
+## Command Prefix
+
+Examples below use `jstar`.
+
+If you do not want a global install, replace `jstar` with `npx jstar-reviewer`.
+
+## 1. Prerequisites
+
+- Node.js 18+
+- Git repository
+- Gemini API key
+- Groq API key
+
+## 2. Install the CLI
+
+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 Repository
+
+```bash
+jstar 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
+jstar init
+```
+
+If indexing fails with a Google 404 for the embedding model, set:
+
+```env
+GEMINI_EMBEDDING_MODEL=gemini-embedding-001
+```
+
+## 6. First Verification Pass
+
+### Option A: Interactive user flow
+
+```bash
+jstar review
+jstar audit
+```
+
+Use this when the user wants the normal CLI/TUI experience.
+
+### Option B: Agent automation flow
+
+```bash
+jstar review --json > .jstar/last-review.json
+jstar audit --json > .jstar/audit_report.json
+```
+
+Use this when an agent needs machine-readable output.
+
+### Option C: Review debate flow
+
+```bash
+jstar chat --headless
+```
+
+Headless commands:
+- `{"action":"list"}`
+- `{"action":"debate","issueId":0,"argument":"..."}`
+- `{"action":"ignore","issueId":0}`
+- `{"action":"accept","issueId":0}`
+- `{"action":"exit"}`
+
+## 7. Common Target Modes
+
+Staged changes:
+
+```bash
+jstar review
+jstar audit
+```
+
+Last commit:
+
+```bash
+jstar review --last
+jstar audit --last
+```
+
+Branch or PR scope:
+
+```bash
+jstar review --pr
+jstar audit --pr
+```
+
+## Outputs
+
+- `.jstar/last-review.md`
+- `.jstar/session.json`
+- `.jstar/audit_report.md`
+- `.jstar/audit_report.json`
+- `.jstar/audit-ignore.json`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takomi",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "🎯 Stop wrestling with AI. Start building with purpose. The artisan's toolkit that transforms AI from chatbot to development partner.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -160,10 +160,11 @@ async function init() {
       // Handle Skills
       if (response.skillMode === 'core') {
         console.log(pc.green('✔ Downloading Core Skills...'));
-        const coreSkills = [
-          'ai-sdk', 'code-review', 'component-analysis',
-          'nextjs-standards', 'security-audit', 'spawn-task',
-          'stitch', 'sync-docs'
+        const coreSkills = [
+          'takomi',
+          'ai-sdk', 'code-review', 'component-analysis',
+          'nextjs-standards', 'security-audit', 'spawn-task',
+          'stitch', 'sync-docs'
         ];
         await copySpecificSkills(coreSkills, skillsDest);
       } else if (response.skillMode === 'all') {
@@ -196,7 +197,7 @@ async function init() {
     console.log(pc.white(`\nNext steps:`));
     if (response.components.includes('agent')) {
       console.log(pc.gray(`1. Your .agent folder is armed and ready.`));
-      console.log(pc.gray(`2. Type '/init_vibecode_genesis' in your IDE to begin.`));
+      console.log(pc.gray(`2. In Codex, say "use takomi genesis" (slash command optional).`));
     }
     console.log(pc.dim(`\n💡 Pro tip: Run "takomi install" to sync this toolkit across all your IDEs.\n`));
 
@@ -263,7 +264,7 @@ async function install() {
       name: 'skillMode',
       message: 'Which skill pack?',
       choices: [
-        { title: 'Core (8 essentials)', value: 'core', description: 'ai-sdk, code-review, nextjs-standards...' },
+        { title: 'Core (Takomi + essentials)', value: 'core', description: 'takomi, ai-sdk, code-review...' },
         { title: `All (${(await getSkills()).length} skills)`, value: 'all' },
         { title: 'Custom selection', value: 'custom' },
       ],

package/src/store.js

@@ -83,9 +83,10 @@ export async function populateSkills(mode) {
     const storeSkills = path.join(STORE_PATH, 'skills');
     await fs.ensureDir(storeSkills);
 
-    const coreSkills = [
-        'ai-sdk', 'code-review', 'component-analysis', 'context7',
-        'nextjs-standards', 'security-audit', 'spawn-task', 'stitch',
+    const coreSkills = [
+        'takomi',
+        'ai-sdk', 'code-review', 'component-analysis', 'context7',
+        'nextjs-standards', 'security-audit', 'spawn-task', 'stitch',
     ];
 
     let skillsToCopy = [];