thinkstack-core 4.0.0__py3-none-any.whl

thinkstack_core/skills/pr-reviewer/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: pr-reviewer
+description: Use when the user writes "Review PR" (or "review PR", "code review", "review pull request", "review https://github.com/.../pull/") followed by a GitHub PR link — performs an expert code review, accepts/merges if standards are met, or rejects with detailed comments
+---
+
+# PR Reviewer
+
+## Trigger
+
+This skill loads when the user prompts with any of:
+- "Review PR"
+- "review PR"
+- "review pull request"
+- "code review"
+- "review https://github.com/.../pull/..."
+
+## Overview
+
+Performs a thorough expert-level code review on a GitHub pull request. The review evaluates code quality, security, correctness, API stability, backward compatibility, test coverage, and CI/CD health. Based on the findings, the PR is either accepted and merged, or rejected with detailed comments explaining what needs to be fixed.
+
+## Workflow
+
+### Step 0: Select Model
+
+Before starting the review, run `opencode models` to list available models:
+
+```bash
+opencode models
+```
+
+Parse the output to find the preferred model:
+- **Preferred**: `fireworks-ai/accounts/fireworks/models/glm-5p2` — check if this ID appears in the model list
+- **Fallback**: `fireworks-ai/accounts/fireworks/models/deepseek-v4-pro` — use if GLM 5.2 is not available
+
+If neither model is listed, prompt the user with the available Fireworks models and ask which to use. If the user doesn't respond, default to the first listed `fireworks-ai` model.
+
+This ensures the review uses the best available model for code analysis without relying on any external gateway.
+
+### Step 1: Identify the PR URL
+
+Extract the full GitHub PR URL from the user's prompt. Validate it matches `https://github.com/*/*/pull/*`.
+
+If no PR URL is found, ask the user to provide one before proceeding.
+
+### Step 2: Fetch PR Metadata
+
+Use `gh pr view <pr-number> --json number,title,state,baseRefName,headRefName,additions,deletions,changedFiles,commits,mergeable,mergeStateStatus,statusCheckRollup,reviews,comments` to get:
+
+- PR title and description
+- Base and head branches
+- File change statistics
+- Commit history
+- Merge status (mergeable, mergeStateStatus)
+- CI status (statusCheckRollup — check conclusion for each check run)
+- Existing reviews and comments
+
+### Step 3: Fetch the Full Diff
+
+Use `gh pr diff <pr-number>` to get the complete diff. This is essential — the diff is the primary artifact for code review.
+
+### Step 4: Identify the Repository Root
+
+Look at the `repo` field or the PR URL to determine the repository's local path. If the repo is not cloned locally, clone it first or skip local checks.
+
+### Step 5: Review Categories
+
+Evaluate the PR across these dimensions, in order:
+
+#### 5a. CI/CD Health (BLOCKING)
+
+Check `statusCheckRollup` from the PR metadata. If ANY check run has `conclusion: "FAILURE"`, investigate the failure:
+- If the failure is caused by the PR's code changes → **blocking issue**
+- If the failure is a pre-existing infrastructure issue (e.g., missing API keys, workflow misconfiguration, unrelated to this PR's changes) → note but do not block
+
+Check `mergeStateStatus`:
+- `"CLEAN"` = good
+- `"UNSTABLE"` = CI issues (investigate)
+- `"DIRTY"` = merge conflict (blocking)
+- `"BEHIND"` = branch needs rebase (blocking)
+
+#### 5b. Security (BLOCKING)
+
+Look for:
+- Secrets, API keys, tokens, or credentials in the diff
+- SQL injection, command injection, or template injection vulnerabilities
+- Authentication/authorization gaps
+- PII handling (logging sensitive data, inadequate redaction)
+- Unsafe deserialization or eval() usage
+- Hardcoded credentials or URLs with embedded tokens
+- Insecure defaults (e.g., `debug=True` in production)
+
+If security issues are found → **REJECT** with explicit vulnerability description, severity, and exact file/line references.
+
+#### 5c. Correctness (BLOCKING)
+
+Look for:
+- Bugs: null pointer, off-by-one, race conditions, logic errors
+- Incorrect error handling: bare excepts, swallowed exceptions, missing cleanup
+- Broken invariants: assumptions that don't hold
+- Incorrect indices, boundary conditions
+- API contract violations (wrong HTTP methods, status codes, response shapes)
+- Database schema issues (missing indexes, nullable issues, migration safety)
+
+If correctness bugs are found → **REJECT** with exact reproduction scenarios.
+
+#### 5d. Backward Compatibility (BLOCKING)
+
+Look for:
+- Breaking changes to public APIs, MCP tool schemas, or CLI interfaces
+- Changes to data formats on disk (`.GCC/` schemas) without migration path
+- Removal of deprecated functions without documented replacement
+- Changes to configuration keys or default behaviors
+- Changes that require user intervention to upgrade
+
+If breaking changes are found without a migration plan or documented justification → **REJECT**.
+
+#### 5e. Test Coverage (HIGH PRIORITY)
+
+Look for:
+- New code without corresponding tests
+- Tests that don't actually test the behavior described
+- Fragile tests (hardcoded paths, timing-dependent, environment-specific)
+- Missing edge case coverage
+
+If new features are added without adequate tests → **REJECT**.
+
+#### 5f. Code Quality
+
+Look for:
+- Dead code, commented-out code, or unused imports
+- Inconsistent naming or formatting with the project's conventions
+- Duplicated code that should be factored out
+- Overly complex functions (too many arguments, too many responsibilities)
+- Missing or misleading docstrings
+- Incorrect type annotations
+- Incorrect use of libraries or frameworks
+- Conflicting patterns or versions of frameworks being introduced
+- Hardcoded values that should be configuration
+
+#### 5g. Architecture & Design
+
+Look for:
+- Violations of project layering (e.g., core library depending on CLI)
+- Mixing concerns in a single module
+- Inappropriate coupling between modules
+- Changes that don't fit the project's design philosophy
+
+### Step 6: Running Tests (REQUIRED for new features)
+
+If the PR adds new code, attempt to run the relevant tests locally:
+```bash
+python -m pytest <relevant test files> -v --tb=short
+```
+
+If any tests fail (other than pre-existing failures), this is a blocking issue.
+
+### Step 7: Decision
+
+**ACCEPT** if:
+- ALL blocking categories (CI, Security, Correctness, Backward Compatibility, Test Coverage) pass with no issues
+- Code quality and architecture are acceptable
+- Tests pass (new and existing)
+
+**REJECT** if:
+- ANY blocking issue is found
+- The issue is severe enough to warrant rejection
+
+### Step 8: Post Decision
+
+If **ACCEPTED**:
+1. Post a detailed review comment summarizing findings, what was checked, and the verdict
+2. Merge the PR using `gh pr merge <pr-number> --squash --subject "<good commit subject>" --body "<detailed commit body>"`
+
+If **REJECTED**:
+1. POST a comprehensive review comment (via `gh pr comment <pr-number>`) with:
+   - Clear verdict: **Rejected: [reason]**
+   - Numbered list of each blocking issue with exact file:line
+   - For each issue: what's wrong, why it matters, and how to fix it
+   - Non-blocking issues as a separate section
+   - What's good about the PR (specific compliments)
+   - Do NOT merge the PR
+
+## Model Selection
+
+This agent selects its model by running `opencode models` at the start of the session and parsing the output:
+
+1. **Preferred**: `fireworks-ai/accounts/fireworks/models/glm-5p2` — GLM 5.2 from Fireworks AI
+2. **Fallback**: `fireworks-ai/accounts/fireworks/models/deepseek-v4-pro` — DeepSeek V4 Pro (if GLM 5.2 is not listed)
+
+The agent must dynamically choose based on what models are available. If neither is found, prompt the user suggesting one of the listed Fireworks models.
+
+Model requirements:
+- Context window: at least 128K tokens (PR diffs can be large)
+- Temperature: 0.1 (low temperature for consistent, deterministic reviews)
+- Tool call support: required (for gh CLI)
+
+## Key Commands
+
+```
+gh pr view <number> --repo <owner/repo> --json <fields>   # Get PR metadata
+gh pr diff <number> --repo <owner/repo>                    # Get full diff
+gh pr comment <number> --repo <owner/repo> --body-file <f> # Post review comment
+gh pr merge <number> --repo <owner/repo> --squash <args>    # Merge PR (accept only)
+```

thinkstack_core/skills/thinkstack-auto-sync/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: thinkstack-auto-sync
+description: Use during an active opencode or Claude Code session to periodically sync learnings and reasoning with the ThinkStack MCP server. Also automatically invoked when a session ends/exits/quits — commits remaining reasoning, pushes learnings to org store, pulls new learnings, and logs the sync summary. Configurable interval (default 5 minutes). Triggers on "thinkstack sync", "thinkstack auto sync", "sync thinkstack", "session ends", "session exits", "session quits", "opencode exits", "claude code exits", "ide closed", or periodically via hook.
+---
+
+# ThinkStack Auto Sync
+
+## Trigger
+
+This skill loads when the user writes any of:
+- "thinkstack sync"
+- "thinkstack auto sync"  
+- "sync thinkstack"
+- "thinkstack sync now"
+- "thinkstack sync start"
+- "start thinkstack auto sync"
+
+It is also wired into the Claude Code `PostToolUse` hook to auto-capture after every mutating tool call, and the `Stop` hook to perform a final sync on session end.
+
+## Overview
+
+Keeps the ThinkStack MCP server in sync with the local `.GCC/` store. Automatically:
+1. Commits any unreasoned changes with a reasoning message
+2. Records sensitivity signals for security-relevant operations
+3. Pushes learnings and context to the org-level MCP store
+4. Checks for sync conflicts post-push
+
+Runs on a **configurable interval** (default: every 5 minutes) or on-demand.
+
+## Configuration
+
+The sync interval is controlled by the ThinkStack config:
+
+```json
+// .GCC/settings.json
+{
+  "reasoning_plus": {
+    "auto_sync_enabled": true,
+    "auto_sync_interval_secs": 300,
+    "auto_sync_on_tool_use": true
+  }
+}
+```
+
+Set via CLI:
+```bash
+thinkstack reasoning-plus config --auto-sync-interval-secs 300
+```
+
+## Workflow
+
+### Interval-Based Periodic Sync
+
+When running in interval mode (every N minutes):
+
+#### Step 1: Commit Reasoning
+
+Before the first tool use since the last sync interval:
+
+```
+MCP Tool: thinkstack_commit
+Args: {
+  "message": "<what was decided and WHY since last sync>",
+  "branch": "<current branch>"
+}
+```
+
+The commit message must explain the *why*, not the *what*.
+
+#### Step 2: Record Sensitivities
+
+For any security-relevant concepts touched since last sync:
+
+```
+MCP Tool: thinkstack_sensitivity_add
+Args: {
+  "concept": "auth|schema|payments|secrets|pii|api|security|config",
+  "signal": "<reasoning text>",
+  "confidence": 0.0-1.0,
+  "disclosure": "PUBLIC|PROTECTED|PRIVATE"
+}
+```
+
+#### Step 3: Push Learnings
+
+Push local learnings to the org store:
+
+```
+MCP Tool: thinkstack_sync_push
+Args: {
+  "bundle": "<gzip-compressed, base64-encoded sync bundle>"
+}
+```
+
+This is constructed from the local delta (what changed since last sync).
+
+#### Step 4: Check for Conflicts
+
+```
+Read .GCC/sync_conflicts.jsonl
+```
+
+Report any new conflicts since the last check. If conflicts are found, escalate to the user.
+
+### Post-Tool-Use Auto Capture
+
+After every mutating tool call (Write, Edit, Bash), the existing `PostToolUse` hook automatically:
+1. Records a reasoning call via `thinkstack_commit` or the capture orchestrator
+2. Extracts learnings from the reasoning
+3. Pushes learnings to the MCP server
+
+This is already configured in the Claude Code hooks installer.
+
+### Session-End Final Sync
+
+When the session ends (`Stop` hook or `thinkstack auto sync stop`):
+
+1. **Final commit**: Record all remaining unreasoned decisions
+2. **Final push**: Push all learnings to the org store
+3. **Sync pull**: Pull any new learnings from the org store that other agents may have contributed
+4. **Conflict check**: Report any unresolved sync conflicts
+5. **Print summary**: 
+
+```
+════ ThinkStack Sync Summary ════
+
+  Session duration: <X> minutes
+  Commits pushed: <N>
+  Learnings extracted: <M>
+  Sensitivities recorded: <P>
+  Sync conflicts: <Q> (0 unresolved)
+  
+  All learnings synced to org store.
+══════════════════════════════
+```
+
+## Periodic Sync Daemon
+
+For continuous background syncing every N minutes, use the ThinkStack daemon:
+
+```bash
+# Start daemon with auto-sync
+thinkstack daemon start --auto-sync --interval 300
+
+# Check status
+thinkstack daemon status
+
+# View logs
+thinkstack daemon logs
+
+# Stop daemon
+thinkstack daemon stop
+```
+
+The daemon watches filesystem changes, automatically commits reasoning events, and pushes sync bundles every `--interval` seconds. It runs as a background process that survives the IDE session.
+
+## Manual Sync (On-Demand)
+
+To manually trigger a full sync at any time:
+
+```bash
+thinkstack sync all
+```
+
+This performs a bidirectional sync: push local changes, pull remote changes, merge with conflict resolution.
+
+## MCP Tools Used
+
+| Tool | Purpose |
+|---|---|
+| `thinkstack_commit` | Record reasoning decisions |
+| `thinkstack_sensitivity_add` | Record sensitivity signals |
+| `thinkstack_sync_push` | Push learnings to org store |
+| `thinkstack_sync_pull` | Pull learnings from org store |
+| `thinkstack_sync_status` | Check sync state |

thinkstack_core/skills/thinkstack-session-start/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: thinkstack-session-start
+description: Use when an opencode or Claude Code session starts — connects to ThinkStack MCP, runs connectivity checks, loads learnings from previous work, commits, and code reviews to bootstrap the current session with full context
+---
+
+# ThinkStack Session Start
+
+## Trigger
+
+This skill loads when the user:
+- Starts a new opencode session
+- Starts a new Claude Code session  
+- Says "thinkstack session start", "thinkstack load context", "load previous learnings"
+- Any first prompt in a freshly started IDE
+
+It is also wired into the Claude Code `UserPromptSubmit` hook and opencode's PreUserPrompt hook to auto-fire on session initialization.
+
+## Overview
+
+Connects to the ThinkStack MCP server for the current project, verifies connectivity, reads recent context (commits, learnings, conflicts, theta), and presents a session bootstrap summary. This ensures every coding session starts with full awareness of prior decisions, risks, and collective learnings.
+
+## Workflow
+
+### Step 1: Connectivity Check
+
+Run the ThinkStack MCP connectivity test to confirm the project is connected:
+
+```
+thinkstack doctor
+```
+
+If `thinkstack doctor` fails with an error, report the issue and fall back to local-only mode. Read from `.GCC/` directly as a fallback.
+
+If successful, confirm: "ThinkStack MCP connected. Loading session context..."
+
+### Step 2: Load Prior Context
+
+Call the `thinkstack_context` MCP tool with a token budget of 8000:
+
+```
+MCP Tool: thinkstack_context
+Args: { "k": 8000 }
+```
+
+This retrieves a bounded context bundle with:
+- Current reasoning roadmap (main.md)
+- Recent reasoning log (log.md)
+- Coordination vector Θ (theta.json)
+- Recent commits
+
+### Step 3: Load Previous Learnings
+
+Call the `thinkstack_reasoning_plus_learning_query` MCP tool:
+
+```
+MCP Tool: thinkstack_reasoning_plus_learning_query
+Args: { "context": "<project name or repo name>", "top_n": 5 }
+```
+
+This returns the top 5 most relevant learnings from previous sessions, ranked by relevance to the current project.
+
+If the MCP tool is unavailable, fall back to reading from `.GCC/reasoning_learnings/learnings/` directly.
+
+### Step 4: Check Sync Status
+
+Call the `thinkstack_sync_status` MCP tool:
+
+```
+MCP Tool: thinkstack_sync_status
+Args: {}
+```
+
+Reports:
+- Number of commits on the server
+- Number of learnings stored
+- Number of theta concepts tracked
+
+### Step 5: Check for Unresolved Conflicts
+
+Read from `.GCC/sync_conflicts.jsonl` or call list_conflicts to get unresolved conflicts from previous sync operations.
+
+Report any unresolved conflicts that need human attention.
+
+### Step 6: Load Code Review Learnings
+
+Search for learnings related to code review patterns:
+
+```
+MCP Tool: thinkstack_learning_search  
+Args: { "query": "code review pattern security quality", "top_n": 3 }
+```
+
+This surfaces learnings from previous PR reviews about patterns to watch for, security pitfalls, or quality standards.
+
+### Step 7: Present Bootstrap Summary
+
+Print a concise session bootstrap summary:
+
+```
+════ ThinkStack Session Bootstrap ════
+
+  MCP Connection: ✅ connected
+  Project: <name>
+  Branch: <current git branch>
+
+  Prior Context:
+    • <number> recent commits loaded
+    • Coordination vector: <number> concepts tracked
+
+  Learnings (from previous sessions):
+    1. [<confidence>] <learning content>
+    2. [<confidence>] <learning content>
+    ...
+
+  Code Review Insights:
+    • <key pattern to follow>
+
+  Sync Status:
+    Commits: <count> | Learnings: <count> | Theta: <count>
+
+  ⚠ <number> unresolved sync conflict(s) — run thinkstack sync conflicts
+
+  Ready to work. All prior context loaded.
+═══════════════════════════════════════
+```
+
+### Fallback
+
+If MCP tools are unreachable, fall back to local `.GCC/` reads:
+- Read `main.md` for reasoning roadmap
+- Read `log.md` for recent activity
+- Read `theta.json` for coordination state
+- List learnings directory for learning count
+- Read `events.log.jsonl` for recent events.
+
+Always report: "MCP server unreachable — using local .GCC/ fallback."