takomi 2.0.5 → 2.0.6

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/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`.