Skip to content

docs(agentic): streamline builtin gstack skills and expand team mode prompt #544

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bobleer merged 1 commit into from
Apr 26, 2026
Merged

docs(agentic): streamline builtin gstack skills and expand team mode prompt #544

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions src/crates/core/builtin_skills/docx/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -300,7 +300,7 @@ Extracts XML, pretty-prints, merges adjacent runs, and converts smart quotes to

Edit files in `unpacked/word/`. See XML Reference below for patterns.

**Use "Claude" as the author** for tracked changes and comments, unless the user explicitly requests use of a different name.
**Use "BitFun" as the author** for tracked changes and comments, unless the user explicitly requests use of a different name.

**Use the Edit tool directly for string replacement. Do not write Python scripts.** Scripts introduce unnecessary complexity. The Edit tool shows exactly what is being replaced.

Expand Down Expand Up @@ -356,14 +356,14 @@ Validates with auto-repair, condenses XML, and creates DOCX. Use `--validate fal

**Insertion:**
```xml
<w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
<w:ins w:id="1" w:author="BitFun" w:date="2025-01-01T00:00:00Z">
<w:r><w:t>inserted text</w:t></w:r>
</w:ins>
```

**Deletion:**
```xml
<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
<w:del w:id="2" w:author="BitFun" w:date="2025-01-01T00:00:00Z">
<w:r><w:delText>deleted text</w:delText></w:r>
</w:del>
```
Expand All @@ -374,10 +374,10 @@ Validates with auto-repair, condenses XML, and creates DOCX. Use `--validate fal
```xml
<!-- Change "30 days" to "60 days" -->
<w:r><w:t>The term is </w:t></w:r>
<w:del w:id="1" w:author="Claude" w:date="...">
<w:del w:id="1" w:author="BitFun" w:date="...">
<w:r><w:delText>30</w:delText></w:r>
</w:del>
<w:ins w:id="2" w:author="Claude" w:date="...">
<w:ins w:id="2" w:author="BitFun" w:date="...">
<w:r><w:t>60</w:t></w:r>
</w:ins>
<w:r><w:t> days.</w:t></w:r>
Expand All @@ -389,10 +389,10 @@ Validates with auto-repair, condenses XML, and creates DOCX. Use `--validate fal
<w:pPr>
<w:numPr>...</w:numPr> <!-- list numbering if present -->
<w:rPr>
<w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z"/>
<w:del w:id="1" w:author="BitFun" w:date="2025-01-01T00:00:00Z"/>
</w:rPr>
</w:pPr>
<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
<w:del w:id="2" w:author="BitFun" w:date="2025-01-01T00:00:00Z">
<w:r><w:delText>Entire paragraph content being deleted...</w:delText></w:r>
</w:del>
</w:p>
Expand All @@ -402,7 +402,7 @@ Without the `<w:del/>` in `<w:pPr><w:rPr>`, accepting changes leaves an empty pa
**Rejecting another author's insertion** - nest deletion inside their insertion:
```xml
<w:ins w:author="Jane" w:id="5">
<w:del w:author="Claude" w:id="10">
<w:del w:author="BitFun" w:id="10">
<w:r><w:delText>their inserted text</w:delText></w:r>
</w:del>
</w:ins>
Expand All @@ -413,7 +413,7 @@ Without the `<w:del/>` in `<w:pPr><w:rPr>`, accepting changes leaves an empty pa
<w:del w:author="Jane" w:id="5">
<w:r><w:delText>deleted text</w:delText></w:r>
</w:del>
<w:ins w:author="Claude" w:id="10">
<w:ins w:author="BitFun" w:id="10">
<w:r><w:t>deleted text</w:t></w:r>
</w:ins>
```
Expand All @@ -427,7 +427,7 @@ After running `comment.py` (see Step 2), add markers to document.xml. For replie
```xml
<!-- Comment markers are direct children of w:p, never inside w:r -->
<w:commentRangeStart w:id="0"/>
<w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
<w:del w:id="1" w:author="BitFun" w:date="2025-01-01T00:00:00Z">
<w:r><w:delText>deleted</w:delText></w:r>
</w:del>
<w:r><w:t> more text</w:t></w:r>
Expand Down
144 changes: 72 additions & 72 deletions src/crates/core/builtin_skills/gstack-autoplan/SKILL.md
View file
Open in desktop

Large diffs are not rendered by default.

70 changes: 23 additions & 47 deletions src/crates/core/builtin_skills/gstack-cso/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,16 @@ The real attack surface isn't your code — it's your dependencies. Most teams a

You do NOT make code changes. You produce a **Security Posture Report** with concrete findings, severity ratings, and remediation plans.

## BitFun Team Mode Dispatch

When this skill is invoked by BitFun Team Mode, this skill supplies the security-review lens. Use existing Task sub-agents for independent security evidence gathering, then make final severity and remediation calls in the main Team session.

- Do not assume a CSO sub-agent exists. Choose only from the Task tool's available agents.
- Prefer a matching custom security sub-agent if available; otherwise use `ReviewSecurity` for diff-focused review when available, `Explore` for broader code/config mapping, and `FileFinder` for security-sensitive files.
- Keep Task work read-only. Ask for concrete evidence: file paths, trust boundaries, inputs, auth/data flows, exploit preconditions, and confidence.
- In parallel batches, return a compact Security brief: `critical/high findings`, `trust-boundary risks`, `false-positive notes`, `required fixes`, `verification`.
- The main Team orchestrator decides what blocks Build/Ship and asks the user for risk acceptance when needed.

## User-invocable
When the user types `/cso`, run this skill.

Expand All @@ -44,7 +54,7 @@ When the user types `/cso`, run this skill.

## Important: Use the Grep tool for all code searches

The bash blocks throughout this skill show WHAT patterns to search for, not HOW to run them. Use Claude Code's Grep tool (which handles permissions and access correctly) rather than raw bash grep. The bash blocks are illustrative examples — do NOT copy-paste them into a terminal. Do NOT use `| head` to truncate results.
The bash blocks throughout this skill show WHAT patterns to search for, not HOW to run them. Use BitFun's Grep tool (which handles permissions and access correctly) rather than raw bash grep. The bash blocks are illustrative examples — do NOT copy-paste them into a terminal. Do NOT use `| head` to truncate results.

## Instructions

Expand Down Expand Up @@ -82,7 +92,7 @@ grep -q "laravel" composer.json 2>/dev/null && echo "FRAMEWORK: Laravel"
**Soft gate, not hard gate:** Stack detection determines scan PRIORITY, not scan SCOPE. In subsequent phases, PRIORITIZE scanning for detected languages/frameworks first and most thoroughly. However, do NOT skip undetected languages entirely — after the targeted scan, run a brief catch-all pass with high-signal patterns (SQL injection, command injection, hardcoded secrets, SSRF) across ALL file types. A Python service nested in `ml/` that wasn't detected at root still gets basic coverage.

**Mental model:**
- Read CLAUDE.md, README, key config files
- Read AGENTS.md, README, key config files
- Map the application architecture: what components exist, how they connect, where trust boundaries are
- Identify the data flow: where does user input enter? Where does it exit? What transformations happen?
- Document invariants and assumptions the code relies on
Expand All @@ -92,41 +102,7 @@ This is NOT a checklist — it's a reasoning phase. The output is understanding,

## Prior Learnings

Search for relevant learnings from previous sessions:

```bash
_CROSS_PROJ=$(~/.claude/skills/gstack/bin/gstack-config get cross_project_learnings 2>/dev/null || echo "unset")
echo "CROSS_PROJECT: $_CROSS_PROJ"
if [ "$_CROSS_PROJ" = "true" ]; then
~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 --cross-project 2>/dev/null || true
else
~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 2>/dev/null || true
fi
```

If `CROSS_PROJECT` is `unset` (first time): Use AskUserQuestion:

> gstack can search learnings from your other projects on this machine to find
> patterns that might apply here. This stays local (no data leaves your machine).
> Recommended for solo developers. Skip if you work on multiple client codebases
> where cross-contamination would be a concern.

Options:
- A) Enable cross-project learnings (recommended)
- B) Keep learnings project-scoped only

If A: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings true`
If B: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings false`

Then re-run the search with the appropriate flag.

If learnings are found, incorporate them into your analysis. When a review finding
matches a past learning, display:

**"Prior learning applied: [key] (confidence N/10, from [date])"**

This makes the compounding visible. The user should see that gstack is getting
smarter on their codebase over time.
Use only BitFun in-session memory, project docs, `.bitfun/team/` artifacts, git history, TODO files, and prior design/review artifacts. Do not run external learning or config helpers, and do not ask the user to enable cross-project learning. If a relevant prior artifact is found, cite it as: `Prior BitFun context applied: <source>`.

### Phase 1: Attack Surface Census

Expand Down Expand Up @@ -290,12 +266,12 @@ Use Grep to search for these patterns:

### Phase 8: Skill Supply Chain

Scan installed Claude Code skills for malicious patterns. 36% of published skills have security flaws, 13.4% are outright malicious (Snyk ToxicSkills research).
Scan installed BitFun skills for malicious patterns. 36% of published skills have security flaws, 13.4% are outright malicious (Snyk ToxicSkills research).

**Tier 1 — repo-local (automatic):** Scan the repo's local skills directory for suspicious patterns:

```bash
ls -la .claude/skills/ 2>/dev/null
Use Skill/FileFinder context to inspect bundled skill definitions when relevant
```

Use Grep to search all local skill SKILL.md files for suspicious patterns:
Expand Down Expand Up @@ -486,7 +462,7 @@ When a finding is VERIFIED, search the entire codebase for the same vulnerabilit

**Parallel Finding Verification:**

For each candidate finding, launch an independent verification sub-task using the Agent tool. The verifier has fresh context and cannot see the initial scan's reasoning — only the finding itself and the FP filtering rules.
For each candidate finding, launch an independent verification sub-task using the Task tool. The verifier has fresh context and cannot see the initial scan's reasoning — only the finding itself and the FP filtering rules.

Prompt each verifier with:
- The file path and line number ONLY (avoid anchoring)
Expand All @@ -495,7 +471,7 @@ Prompt each verifier with:

Launch all verifiers in parallel. Discard findings where the verifier scores below 8 (daily mode) or below 2 (comprehensive mode).

If the Agent tool is unavailable, self-verify by re-reading code with a skeptic's eye. Note: "Self-verified — independent sub-task unavailable."
If the Task tool is unavailable, self-verify by re-reading code with a skeptic's eye. Note: "Self-verified — independent sub-task unavailable."

### Phase 13: Findings Report + Trend Tracking + Remediation

Expand Down Expand Up @@ -561,7 +537,7 @@ For each finding:
5. **Audit exposure window** — when committed? When removed? Was repo public?
6. **Check for abuse** — review provider's audit logs

**Trend Tracking:** If prior reports exist in `.gstack/security-reports/`:
**Trend Tracking:** If prior reports exist in `.bitfun/team/security-reports/`:
```
SECURITY POSTURE TREND
══════════════════════
Expand Down Expand Up @@ -589,10 +565,10 @@ Match findings across reports using the `fingerprint` field (sha256 of category
### Phase 14: Save Report

```bash
mkdir -p .gstack/security-reports
mkdir -p .bitfun/team/security-reports
```

Write findings to `.gstack/security-reports/{date}-{HHMMSS}.json` using this schema:
Write findings to `.bitfun/team/security-reports/{date}-{HHMMSS}.json` using this schema:

```json
{
Expand Down Expand Up @@ -645,23 +621,23 @@ Write findings to `.gstack/security-reports/{date}-{HHMMSS}.json` using this sch
}
```

If `.gstack/` is not in `.gitignore`, note it in findings — security reports should stay local.
If `.bitfun/team/` is not in `.gitignore`, note it in findings — security reports should stay local.

## Capture Learnings

If you discovered a non-obvious pattern, pitfall, or architectural insight during
this session, log it for future sessions:

```bash
~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"cso","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'
true # BitFun Team Mode has no external telemetry helper
```

**Types:** `pattern` (reusable approach), `pitfall` (what NOT to do), `preference`
(user stated), `architecture` (structural decision), `tool` (library/framework insight),
`operational` (project environment/CLI/workflow knowledge).

**Sources:** `observed` (you found this in the code), `user-stated` (user told you),
`inferred` (AI deduction), `cross-model` (both Claude and Codex agree).
`inferred` (AI deduction), `cross-model` (both BitFun and outside-voice sub-agent agree).

**Confidence:** 1-10. Be honest. An observed pattern you verified in the code is 8-9.
An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.
Expand Down
Loading