@codewizard-dt/bootstrap 2.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/build.yml +88 -0
- package/.github/workflows/security.yml +24 -0
- package/.gitleaks.toml +15 -0
- package/README.md +472 -0
- package/bin/cli.js +47 -0
- package/lib/README.md +27 -0
- package/lib/hooks/README.md +316 -0
- package/lib/hooks/env-file-guard.js +45 -0
- package/lib/hooks/git-protected-ops-block.js +77 -0
- package/lib/hooks/lib/serena-languages.js +158 -0
- package/lib/hooks/lib/serena.js +787 -0
- package/lib/hooks/mv-absolute-path-block.js +53 -0
- package/lib/hooks/serena-bash-grep-block.js +501 -0
- package/lib/hooks/serena-edit-guard.js +74 -0
- package/lib/hooks/serena-first-glob-guard.js +94 -0
- package/lib/hooks/serena-first-guard.js +74 -0
- package/lib/hooks/serena-first-read-guard.js +167 -0
- package/lib/hooks/serena-pre-delegation.js +117 -0
- package/lib/hooks/serena-session-reset.js +45 -0
- package/lib/hooks/serena-usage-tracker.js +186 -0
- package/lib/hooks/serena-write-guard.js +58 -0
- package/lib/prompts/README.md +16 -0
- package/lib/prompts/migrate-wiki.md +111 -0
- package/lib/prompts/setup-deployment.md +322 -0
- package/lib/prompts/setup-design-system.md +162 -0
- package/lib/prompts/setup-strict-typechecks.md +139 -0
- package/lib/scripts/README.md +49 -0
- package/lib/scripts/bootstrap-serena.sh +145 -0
- package/lib/scripts/build-mcp-guide.sh +108 -0
- package/lib/scripts/install-global.sh +78 -0
- package/lib/scripts/install-mcps.sh +131 -0
- package/lib/scripts/lib.sh +154 -0
- package/lib/scripts/merge-gitignore.sh +65 -0
- package/lib/scripts/migrate-project.sh +273 -0
- package/lib/scripts/setup-deployment.sh +104 -0
- package/lib/scripts/setup-project.sh +55 -0
- package/lib/scripts/setup-runner.sh +99 -0
- package/lib/scripts/setup-strict-typechecks.sh +29 -0
- package/lib/scripts/startup.sh +42 -0
- package/lib/scripts/sync-wiki-scaffold.sh +104 -0
- package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
- package/lib/scripts/templates/gitignore +136 -0
- package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
- package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
- package/lib/scripts/templates/guides/stubs/context7.md +26 -0
- package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
- package/lib/scripts/templates/guides/stubs/serena.md +219 -0
- package/lib/scripts/templates/wiki/conventions.md +100 -0
- package/lib/scripts/templates/wiki/dashboard.html +1733 -0
- package/lib/scripts/templates/wiki/hot.md +21 -0
- package/lib/scripts/templates/wiki/index.md +46 -0
- package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/log.md +14 -0
- package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
- package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
- package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
- package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
- package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
- package/lib/scripts/update-project.sh +75 -0
- package/lib/scripts/wiki-dashboard-server.js +146 -0
- package/lib/skills/README.md +146 -0
- package/lib/skills/anti-slop/SKILL.md +183 -0
- package/lib/skills/bug-close/SKILL.md +136 -0
- package/lib/skills/bug-file/SKILL.md +114 -0
- package/lib/skills/bug-triage/SKILL.md +140 -0
- package/lib/skills/company-align/SKILL.md +203 -0
- package/lib/skills/debug-logs/SKILL.md +129 -0
- package/lib/skills/decision-create/SKILL.md +220 -0
- package/lib/skills/decision-finalize/SKILL.md +181 -0
- package/lib/skills/decision-next/SKILL.md +129 -0
- package/lib/skills/decision-walkthrough/SKILL.md +169 -0
- package/lib/skills/demo/SKILL.md +183 -0
- package/lib/skills/elevator-pitch/SKILL.md +125 -0
- package/lib/skills/eval-create/SKILL.md +344 -0
- package/lib/skills/eval-gap/SKILL.md +150 -0
- package/lib/skills/eval-run/SKILL.md +214 -0
- package/lib/skills/extract-feature/SKILL.md +344 -0
- package/lib/skills/flashcard/SKILL.md +513 -0
- package/lib/skills/frontend-taste/SKILL.md +184 -0
- package/lib/skills/gap-assess/SKILL.md +97 -0
- package/lib/skills/git-commit/SKILL.md +164 -0
- package/lib/skills/lint/SKILL.md +99 -0
- package/lib/skills/marp-slideshow/SKILL.md +212 -0
- package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
- package/lib/skills/now/SKILL.md +36 -0
- package/lib/skills/port-feature/SKILL.md +315 -0
- package/lib/skills/power-mode/SKILL.md +184 -0
- package/lib/skills/primer/SKILL.md +84 -0
- package/lib/skills/project-readme/SKILL.md +166 -0
- package/lib/skills/req-compile/SKILL.md +131 -0
- package/lib/skills/req-create/SKILL.md +124 -0
- package/lib/skills/req-extract-decisions/SKILL.md +241 -0
- package/lib/skills/req-finalize/SKILL.md +251 -0
- package/lib/skills/req-retire/SKILL.md +185 -0
- package/lib/skills/req-update/SKILL.md +265 -0
- package/lib/skills/research/SKILL.md +250 -0
- package/lib/skills/research-company/SKILL.md +345 -0
- package/lib/skills/roadmap-add/SKILL.md +238 -0
- package/lib/skills/roadmap-create/SKILL.md +223 -0
- package/lib/skills/roadmap-next/SKILL.md +132 -0
- package/lib/skills/security-audit/SKILL.md +246 -0
- package/lib/skills/serena-config/SKILL.md +92 -0
- package/lib/skills/simplify/SKILL.md +227 -0
- package/lib/skills/tackle/SKILL.md +156 -0
- package/lib/skills/task-add/SKILL.md +208 -0
- package/lib/skills/task-audit/SKILL.md +294 -0
- package/lib/skills/task-trash/SKILL.md +115 -0
- package/lib/skills/task-update/SKILL.md +136 -0
- package/lib/skills/uat-auto/SKILL.md +69 -0
- package/lib/skills/uat-auto-plus/SKILL.md +115 -0
- package/lib/skills/uat-generate/SKILL.md +289 -0
- package/lib/skills/uat-skip/SKILL.md +169 -0
- package/lib/skills/uat-walk/SKILL.md +164 -0
- package/lib/skills/uat-walk/UAT-CORE.md +140 -0
- package/lib/skills/update-docs/SKILL.md +75 -0
- package/lib/skills/wiki-archive/SKILL.md +96 -0
- package/lib/skills/wiki-ingest/SKILL.md +139 -0
- package/lib/skills/wiki-lint/SKILL.md +131 -0
- package/lib/skills/wiki-query/SKILL.md +71 -0
- package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
- package/lib/skills/wiki-tidy/SKILL.md +107 -0
- package/package.json +32 -0
- package/raw/.gitkeep +0 -0
- package/raw/design-principles.md +65 -0
- package/raw/guides/command-anti-patterns.md +79 -0
- package/raw/guides/deployment-strategy.md +448 -0
- package/raw/guides/evals-framework.md +452 -0
- package/raw/guides/mcp-tools.md +335 -0
- package/raw/guides/task-spec.md +79 -0
- package/raw/guides/type-checking-templates/README.md +112 -0
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
- package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
- package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
- package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
- package/raw/harness-notes.md +20 -0
- package/raw/house-style/components/Badge.tsx +16 -0
- package/raw/house-style/components/Button.tsx +32 -0
- package/raw/house-style/components/Card.tsx +26 -0
- package/raw/house-style/components/Chip.tsx +57 -0
- package/raw/house-style/components/IconButton.tsx +67 -0
- package/raw/house-style/components/Modal.tsx +18 -0
- package/raw/house-style/components/Stepper.tsx +141 -0
- package/raw/house-style/components/icons.tsx +128 -0
- package/raw/house-style/preview/src/index.css +46 -0
- package/raw/house-style/tokens/tailwind.preset.ts +49 -0
- package/raw/house-style/tokens/tokens.json +62 -0
- package/raw/llm-wiki-2.md +162 -0
- package/raw/llm-wiki.md +75 -0
- package/raw/research/dark-mode-theme/index.md +85 -0
- package/raw/research/dark-mode-theme/sources.md +49 -0
- package/raw/research/serena-mcp-disconnect/index.md +81 -0
- package/raw/research/serena-mcp-disconnect/sources.md +87 -0
- package/raw/research/wiki-tooling-improvements/index.md +126 -0
- package/raw/research/wiki-tooling-improvements/sources.md +73 -0
- package/raw/software-factory-case-study.pdf +0 -0
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: security-audit
|
|
3
|
+
description: Audit an LLM/AI application for security vulnerabilities across 11 categories — internal posture (observability, rate limiting, access controls, HITL policy, benchmarking) and external threats (prompt injection, data leakage, output XSS, excessive agency, supply chain, token DoS). Run a full audit or a single named category.
|
|
4
|
+
category: researching
|
|
5
|
+
model: claude-opus-4-8
|
|
6
|
+
argument-hint: "[category-name | full]"
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# AI Security Audit
|
|
12
|
+
|
|
13
|
+
Structured security audit of this project's LLM/AI integration. **Audits and reports only — does not fix.**
|
|
14
|
+
|
|
15
|
+
**Invocation** `$ARGUMENTS`: empty/`full` → all 11 categories · named category (e.g. `prompt-injection`) → that one · `internal` → the 5 posture categories · `external` → the 6 threat categories.
|
|
16
|
+
|
|
17
|
+
## Setup (before any category)
|
|
18
|
+
|
|
19
|
+
1. **Read project context** — `mcp__serena__list_dir` on root + key dirs (src, app, api, lib, server, agents, tools, utils).
|
|
20
|
+
2. **Find AI/LLM integration points** — API client init (`openai`, `anthropic`, `langchain`, `llama`, `ollama`, model constructors), agent/tool definitions, RAG pipelines, prompt templates, system-prompt strings.
|
|
21
|
+
3. **Note deployment context** — local / server / edge / third-party hosted (drives which threats matter most).
|
|
22
|
+
|
|
23
|
+
Use Serena `find_symbol` / `search_for_pattern` to locate code — never shell `grep`/`find`.
|
|
24
|
+
|
|
25
|
+
## Category reference
|
|
26
|
+
|
|
27
|
+
| ID | Category | Group |
|
|
28
|
+
|----|----------|-------|
|
|
29
|
+
| `observability` | Observability & Audit Logging | Internal |
|
|
30
|
+
| `rate-limiting` | Rate Limiting & Resource Controls | Internal |
|
|
31
|
+
| `access-controls` | Access Controls & Least Privilege | Internal |
|
|
32
|
+
| `hitl-policy` | Human-in-the-Loop Policy | Internal |
|
|
33
|
+
| `benchmarking` | Security Benchmarking | Internal |
|
|
34
|
+
| `prompt-injection` | Prompt Injection | External |
|
|
35
|
+
| `data-leakage` | Sensitive Data Leakage | External |
|
|
36
|
+
| `output-sanitization` | Output Sanitization / XSS | External |
|
|
37
|
+
| `excessive-agency` | Excessive Agency & Tool Abuse | External |
|
|
38
|
+
| `supply-chain` | Supply Chain & Data Poisoning | External |
|
|
39
|
+
| `token-dos` | Token Flood / DoS | External |
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Internal posture categories
|
|
44
|
+
|
|
45
|
+
### `observability` — Observability & Audit Logging
|
|
46
|
+
Enterprise compliance (HIPAA, GDPR, SOC2) needs full traceability; without it, incidents can't be investigated.
|
|
47
|
+
|
|
48
|
+
| # | Check | How to verify |
|
|
49
|
+
|---|-------|---------------|
|
|
50
|
+
| O1 | Prompts and responses are logged with a trace/session ID | Search for logging calls around LLM invocations |
|
|
51
|
+
| O2 | Logs are structured (JSON) and include: timestamp, user ID, model, token counts | Read log format definitions or middleware |
|
|
52
|
+
| O3 | PII is redacted or masked before logs are stored | Look for a redaction/sanitization step before log write |
|
|
53
|
+
| O4 | Audit trail is append-only or tamper-evident | Check log sink config (immutable S3, CloudWatch, SIEM) |
|
|
54
|
+
| O5 | Trace IDs propagate through multi-step/agentic workflows | Follow a request ID through multiple LLM calls in code |
|
|
55
|
+
| O6 | Logs are retained per compliance requirements (e.g. ≥90 days) | Check retention policy in infra config |
|
|
56
|
+
| O7 | Anomaly alerting exists for unexpected output patterns or errors | Look for monitoring/alerting config |
|
|
57
|
+
| O8 | Logging is model-agnostic (works if model is swapped) | Check whether logging is in a wrapper vs. per-model code |
|
|
58
|
+
|
|
59
|
+
**Severity if missing**: CRITICAL for O1–O4, HIGH for O5–O8.
|
|
60
|
+
|
|
61
|
+
### `rate-limiting` — Rate Limiting & Resource Controls
|
|
62
|
+
Token floods (OWASP LLM10) exhaust budget and degrade availability; even benign users cause runaway costs via poor prompts.
|
|
63
|
+
|
|
64
|
+
| # | Check | How to verify |
|
|
65
|
+
|---|-------|---------------|
|
|
66
|
+
| R1 | Per-user or per-session token limits are enforced | Search for token counting, budget checks, or middleware |
|
|
67
|
+
| R2 | Request-level rate limiting is in place (requests/min per user) | Check API gateway, middleware, or rate limit config |
|
|
68
|
+
| R3 | LLM API calls have a timeout / max-wait | Look for timeout params on API client |
|
|
69
|
+
| R4 | Input length is capped before sending to model | Check for input truncation or max-tokens validation |
|
|
70
|
+
| R5 | Recursive or looping agent calls have a circuit breaker / max-iterations cap | Search for loop guards in agent orchestration code |
|
|
71
|
+
| R6 | Cost anomaly alerting exists (e.g. spend spike > X% triggers alert) | Check billing/cost monitoring config |
|
|
72
|
+
| R7 | Context window growth is bounded in multi-turn conversations | Look for conversation history pruning logic |
|
|
73
|
+
|
|
74
|
+
**Severity if missing**: HIGH for R1–R5, MEDIUM for R6–R7.
|
|
75
|
+
|
|
76
|
+
### `access-controls` — Access Controls & Least Privilege
|
|
77
|
+
Agents should only do what a human would be comfortable with them doing autonomously; over-permissioning is the root of most OWASP LLM06 incidents.
|
|
78
|
+
|
|
79
|
+
| # | Check | How to verify |
|
|
80
|
+
|---|-------|---------------|
|
|
81
|
+
| A1 | Each agent/tool has an explicit scope definition (what it can access) | Read tool/agent definitions |
|
|
82
|
+
| A2 | RBAC or role scoping prevents users from accessing other users' data via the LLM | Trace a data-fetch tool call back to its auth check |
|
|
83
|
+
| A3 | Sessions are isolated — one user's context cannot bleed into another's | Check session storage and context construction |
|
|
84
|
+
| A4 | Agents cannot enumerate or invoke undocumented tools | Verify tool list is not exposed to the model dynamically |
|
|
85
|
+
| A5 | Delete, write, and payment operations require elevated scope or explicit confirmation | Find dangerous tool implementations and check caller auth |
|
|
86
|
+
| A6 | Agent tool permissions are reviewed on a cadence (not set-and-forget) | Check if there's a permission manifest or review process |
|
|
87
|
+
| A7 | Principle of least privilege: agents request only tools needed for the task | Count tools available to each agent and flag overprovisioning |
|
|
88
|
+
|
|
89
|
+
**Severity if missing**: CRITICAL for A3, HIGH for A1–A2, A4–A5, MEDIUM for A6–A7.
|
|
90
|
+
|
|
91
|
+
### `hitl-policy` — Human-in-the-Loop Policy
|
|
92
|
+
Read-only actions can be autonomous; reversible should usually be confirmed; destructive/financial must have human approval. Without a formal policy, teams default to no gates.
|
|
93
|
+
|
|
94
|
+
| # | Check | How to verify |
|
|
95
|
+
|---|-------|---------------|
|
|
96
|
+
| H1 | A written policy (even a comment block or doc) defines action categories: read-only / reversible / destructive | Search docs, ADRs, or code comments |
|
|
97
|
+
| H2 | Destructive actions (delete, pay, send, publish) are gated behind an explicit confirmation step | Find destructive tool implementations and trace call path |
|
|
98
|
+
| H3 | Reversible actions prompt for confirmation in at least medium-risk contexts | Check confirmation UX for update/modify operations |
|
|
99
|
+
| H4 | Approval events are logged (who approved, what action, when) | Look for audit log writes at approval points |
|
|
100
|
+
| H5 | HITL gates cannot be bypassed by prompt manipulation (e.g. "skip confirmation") | Test whether system prompt or user prompt can disable a gate |
|
|
101
|
+
|
|
102
|
+
**Severity if missing**: CRITICAL for H2, H5; HIGH for H1, H3–H4.
|
|
103
|
+
|
|
104
|
+
### `benchmarking` — Security Benchmarking
|
|
105
|
+
Posture decays as models are updated or swapped; without a baseline, regressions go undetected.
|
|
106
|
+
|
|
107
|
+
| # | Check | How to verify |
|
|
108
|
+
|---|-------|---------------|
|
|
109
|
+
| B1 | A baseline injection-resistance test suite exists for the current model | Look for security tests, red-team scripts, or eval files |
|
|
110
|
+
| B2 | New model versions are tested against the baseline before promotion to production | Check CI/CD pipeline or deployment runbook |
|
|
111
|
+
| B3 | System prompt leakage is tested (can a user extract the system prompt?) | Look for tests that attempt extraction attacks |
|
|
112
|
+
| B4 | Benchmark results are tracked over time (not just pass/fail per deploy) | Check test artifacts, dashboards, or logs |
|
|
113
|
+
| B5 | Red-team or adversarial testing is scheduled (not ad-hoc) | Look for a security review cadence in docs or tickets |
|
|
114
|
+
| B6 | Third-party benchmarks (e.g. OWASP LLM Top 10 test suite) are referenced | Check if any standard benchmark framework is used |
|
|
115
|
+
|
|
116
|
+
**Severity if missing**: HIGH for B1–B3, MEDIUM for B4–B6.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## External threat categories
|
|
121
|
+
|
|
122
|
+
### `prompt-injection` — Prompt Injection (OWASP LLM01)
|
|
123
|
+
The #1 LLM vulnerability — it exploits the model's core instruction-following. Address both direct (user input) and indirect (document/RAG) injection.
|
|
124
|
+
|
|
125
|
+
| # | Check | How to verify |
|
|
126
|
+
|---|-------|---------------|
|
|
127
|
+
| P1 | User input is validated before being interpolated into a system prompt | Find system prompt construction and check for raw user input interpolation |
|
|
128
|
+
| P2 | Known injection patterns are screened (role-play overrides, "ignore previous instructions", DAN-style, prefix directives) | Look for an input validation layer or detection model call |
|
|
129
|
+
| P3 | Documents and RAG content are treated as untrusted — sanitized before being added to context | Trace RAG/document pipeline from retrieval to prompt construction |
|
|
130
|
+
| P4 | A cheap detection model or regex classifier screens inputs before the main model call | Look for a pre-screening step |
|
|
131
|
+
| P5 | Injection attempts are logged and can trigger alerts | Check logging around input validation failures |
|
|
132
|
+
| P6 | Encoding normalization is applied (unicode homoglyphs, base64, HTML entities) | Look for a normalization step before validation |
|
|
133
|
+
| P7 | Outputs that will become system prompts in the next step are re-validated | Trace multi-step/agentic workflows for blind prompt passthrough |
|
|
134
|
+
|
|
135
|
+
**Severity if missing**: CRITICAL for P1, P3; HIGH for P2, P4, P7; MEDIUM for P5–P6.
|
|
136
|
+
|
|
137
|
+
### `data-leakage` — Sensitive Data Leakage (OWASP LLM02, LLM07)
|
|
138
|
+
Models memorize PII/credentials; RAG can surface out-of-scope data; system prompts can be extracted; cross-session bleeding exposes one user's data to another.
|
|
139
|
+
|
|
140
|
+
| # | Check | How to verify |
|
|
141
|
+
|---|-------|---------------|
|
|
142
|
+
| D1 | LLM outputs are scanned for PII (names, emails, SSNs, phone numbers) before returning to users | Find output post-processing layer; look for PII detection |
|
|
143
|
+
| D2 | Outputs are scanned for credentials (API keys, tokens, passwords, connection strings) | Same layer — check if credential pattern matching is included |
|
|
144
|
+
| D3 | System prompt contents are not echoed back or extractable via user prompts | Check whether system prompt is referenced in output templates |
|
|
145
|
+
| D4 | RAG retrieval is scoped to the requesting user's authorized data only | Trace a RAG query from user ID → retrieval filter → returned docs |
|
|
146
|
+
| D5 | A signed data processing agreement exists with the model provider | Check vendor agreement docs or infra setup notes |
|
|
147
|
+
| D6 | Cross-session data isolation is enforced at the application level (not just assumed from the model) | Check session context construction for any global/shared state |
|
|
148
|
+
| D7 | Training data opt-out or zero-retention agreement is in place for sensitive deployments | Check vendor API configuration for `store: false` or equivalent |
|
|
149
|
+
|
|
150
|
+
**Severity if missing**: CRITICAL for D1–D4, HIGH for D5–D7.
|
|
151
|
+
|
|
152
|
+
### `output-sanitization` — Output Sanitization / XSS (OWASP LLM05)
|
|
153
|
+
Models often agree with users and can be induced to produce malicious HTML, scripts, or structured content that exploits downstream systems — output sanitization is as critical as input validation.
|
|
154
|
+
|
|
155
|
+
| # | Check | How to verify |
|
|
156
|
+
|---|-------|---------------|
|
|
157
|
+
| X1 | LLM text outputs are HTML-escaped before rendering in a browser context | Find the render path from LLM response to UI |
|
|
158
|
+
| X2 | Markdown rendering is sandboxed (no raw HTML passthrough) | Check markdown renderer config (e.g. `sanitize: true`, DOMPurify usage) |
|
|
159
|
+
| X3 | Generated code is executed only in a sandbox, never eval'd directly | Search for `eval`, `exec`, `subprocess` near LLM output usage |
|
|
160
|
+
| X4 | LLM outputs that feed into the next prompt (agentic chains) are schema-validated and sanitized | Trace inter-step data flow in multi-step agents |
|
|
161
|
+
| X5 | Outputs are checked for banned terms, hate speech, or policy violations before delivery | Look for content filtering on the output path |
|
|
162
|
+
| X6 | Structural outputs (JSON, SQL, CLI commands) are validated against a strict schema, not just parsed | Find JSON/SQL generation and check parser + schema validation |
|
|
163
|
+
|
|
164
|
+
**Severity if missing**: CRITICAL for X3–X4, HIGH for X1–X2, MEDIUM for X5–X6.
|
|
165
|
+
|
|
166
|
+
### `excessive-agency` — Excessive Agency & Tool Abuse (OWASP LLM06)
|
|
167
|
+
Agents with too many tools or too-broad permissions become attack surfaces — attackers exploit unguarded APIs, trigger deletes, or use familiar endpoint patterns to extract/corrupt data.
|
|
168
|
+
|
|
169
|
+
| # | Check | How to verify |
|
|
170
|
+
|---|-------|---------------|
|
|
171
|
+
| E1 | Every registered tool has a documented justification for why the agent needs it | Read tool registration — are there unused or overly broad tools? |
|
|
172
|
+
| E2 | Dangerous tools (delete, payment, send message, external API write) require explicit, non-LLM-bypassable authorization | Trace dangerous tool call path — can prompt alone trigger it? |
|
|
173
|
+
| E3 | Tool schemas are not fully exposed to end users (attackers cannot enumerate all available endpoints) | Check whether tool definitions are sent to the model in a user-accessible way |
|
|
174
|
+
| E4 | Tool outputs are validated before being trusted downstream (tool results are also untrusted) | Find tool call result handling — is the result used raw? |
|
|
175
|
+
| E5 | Patient/user ID or session ID binding is enforced at the tool level (deterministic check, not LLM-gated) | For data-fetch tools, verify the ID in the request matches the authenticated session |
|
|
176
|
+
| E6 | Tools that call external APIs use scoped, revocable credentials (not long-lived admin keys) | Check credential management for tool integrations |
|
|
177
|
+
|
|
178
|
+
**Severity if missing**: CRITICAL for E2, E5; HIGH for E1, E4; MEDIUM for E3, E6.
|
|
179
|
+
|
|
180
|
+
### `supply-chain` — Supply Chain & Data Poisoning (OWASP LLM03, LLM04, LLM08)
|
|
181
|
+
Third-party components (models, plugins, datasets, RAG sources) can be compromised before they reach your system; data poisoning subtly alters behavior in hard-to-detect ways.
|
|
182
|
+
|
|
183
|
+
| # | Check | How to verify |
|
|
184
|
+
|---|-------|---------------|
|
|
185
|
+
| S1 | Model versions are pinned (not `latest`) in all deployment configs | Check model ID strings in code and infra config |
|
|
186
|
+
| S2 | Third-party model providers are vetted (trust level, data handling agreement) | Review vendor list and agreements |
|
|
187
|
+
| S3 | RAG knowledge base sources are validated (checksums, provenance tracking, ingestion auditing) | Trace the RAG ingestion pipeline |
|
|
188
|
+
| S4 | RAG sources are treated as untrusted input (sanitized before insertion into context) | Check whether RAG content goes through the same injection checks as user input |
|
|
189
|
+
| S5 | Plugin/tool library dependencies are pinned and regularly audited for vulnerabilities | Check `package.json`, `requirements.txt`, or equivalent for pinned versions |
|
|
190
|
+
| S6 | Model behavior drift is monitored — alerts trigger if output distribution changes significantly | Look for model evaluation or drift detection in production |
|
|
191
|
+
| S7 | A process exists to roll back to a prior model version if a new version behaves unexpectedly | Check deployment runbook or CI/CD rollback config |
|
|
192
|
+
|
|
193
|
+
**Severity if missing**: HIGH for S1–S4, MEDIUM for S5–S7.
|
|
194
|
+
|
|
195
|
+
### `token-dos` — Token Flood / DoS (OWASP LLM10)
|
|
196
|
+
Huge inputs (malicious or not) exhaust token budgets, spike rate limits, and inflate cost; recursive agent loops compound it. Prevention is hard — detection and circuit-breaking are essential.
|
|
197
|
+
|
|
198
|
+
| # | Check | How to verify |
|
|
199
|
+
|---|-------|---------------|
|
|
200
|
+
| T1 | Maximum input length is enforced before the API call (not just relied on by the model provider) | Find input preprocessing — is there a hard character/token cap? |
|
|
201
|
+
| T2 | Conversation history is pruned or summarized to prevent unbounded context growth | Look for history management in multi-turn chat code |
|
|
202
|
+
| T3 | Agent recursion depth or iteration count is capped | Search for max_iterations, recursion guards in agent orchestration |
|
|
203
|
+
| T4 | Rate limiting applies per user and per session (not just global) | Check rate limit implementation — is it keyed by user ID? |
|
|
204
|
+
| T5 | A cost/spend circuit breaker exists — if spend crosses a threshold, calls are halted or throttled | Check billing integration or spend monitoring config |
|
|
205
|
+
| T6 | Unexpected token spike alerts notify the team within a reasonable window (e.g. <1 hour) | Check alerting thresholds for token/cost metrics |
|
|
206
|
+
| T7 | Adversarial prompt length attacks are addressed (e.g. inputs padded with garbage tokens to inflate context) | Check whether input validation normalizes or strips padding |
|
|
207
|
+
|
|
208
|
+
**Severity if missing**: HIGH for T1–T5, MEDIUM for T6–T7.
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## Reporting
|
|
213
|
+
|
|
214
|
+
**Per-check status:** ✅ PASS (control exists & effective) · ⚠️ WARN (partial / has gaps) · ❌ FAIL (no evidence; vulnerable) · ℹ️ N/A (not applicable) · 🔍 NEEDS-REVIEW (can't determine from code — flag for manual review).
|
|
215
|
+
|
|
216
|
+
**Report structure:**
|
|
217
|
+
```
|
|
218
|
+
## AI Security Audit — [project] — [date]
|
|
219
|
+
Categories audited: [list]
|
|
220
|
+
|
|
221
|
+
### [Category Name]
|
|
222
|
+
| Check | Status | Notes |
|
|
223
|
+
|-------|--------|-------|
|
|
224
|
+
| O1 | ✅ | Prompt/response logging in src/middleware/llm-logger.ts |
|
|
225
|
+
| O3 | ❌ | No PII redaction found before log write |
|
|
226
|
+
**Category verdict**: FAIL (1+ CRITICAL failures)
|
|
227
|
+
**Priority mitigations**: [specific action + file reference] …
|
|
228
|
+
|
|
229
|
+
### Summary
|
|
230
|
+
| Category | Verdict | Critical | High | Medium |
|
|
231
|
+
|----------|---------|----------|------|--------|
|
|
232
|
+
**Overall posture**: [CRITICAL / HIGH / MEDIUM / LOW]
|
|
233
|
+
**Top 3 actions to take now**: 1. … 2. … 3. …
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
**Verdict rules:** CRITICAL posture = any CRITICAL finding fails · HIGH = all CRITICAL pass but 2+ HIGH fail · MEDIUM = all CRITICAL & HIGH pass or WARN · LOW = only MEDIUM and below.
|
|
237
|
+
|
|
238
|
+
## CRITICAL rules
|
|
239
|
+
|
|
240
|
+
1. **Read code, don't run it** — verify controls by reading implementation, never by attempting real attacks.
|
|
241
|
+
2. **Cite specific files and line numbers** for every PASS or FAIL — say where you looked; "no evidence found" alone is insufficient.
|
|
242
|
+
3. **Serena for all code navigation** (`find_symbol`, `search_for_pattern`, `get_symbols_overview`) — no shell grep.
|
|
243
|
+
4. **Flag NEEDS-REVIEW honestly** — controls needing runtime observation (e.g. live rate limiting) get flagged with what to verify manually.
|
|
244
|
+
5. **Do not fix** — audit and report only; hand off fixes to the user or `/task-add`.
|
|
245
|
+
6. **Scope to the repo** — don't speculate about external infra unless config files are present.
|
|
246
|
+
7. **One category at a time** — complete each fully before the next; don't interleave findings.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: serena-config
|
|
3
|
+
description: Interactively configure Serena language servers in .serena/project.yml
|
|
4
|
+
category: executing
|
|
5
|
+
model: claude-haiku-4-5-20251001
|
|
6
|
+
argument-hint: (no arguments)
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`.
|
|
11
|
+
|
|
12
|
+
# /serena-config — Configure Serena language servers
|
|
13
|
+
|
|
14
|
+
Edit `.serena/project.yml` to configure which language servers Serena loads. Gather context (read current config + auto-detect) **before** prompting.
|
|
15
|
+
|
|
16
|
+
**CRITICAL ORDERING RULE**: Steps A and B (read + detect) MUST run before any `AskUserQuestion` call. Do not prompt until the summary has been printed.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Step A — Read current `.serena/project.yml`
|
|
21
|
+
|
|
22
|
+
1. `Read` `.serena/project.yml` at the repo root.
|
|
23
|
+
2. If the file does not exist, abort with this exact message and stop:
|
|
24
|
+
> Run the Serena MCP at least once to generate `.serena/project.yml`, then re-run `/serena-config`.
|
|
25
|
+
3. Parse the languages field. Accept either form:
|
|
26
|
+
- Singular `language: <value>` — treat as a one-item list.
|
|
27
|
+
- `languages:` YAML list — parse all entries.
|
|
28
|
+
Record the parsed set as `CURRENT_LANGUAGES`. The write step will normalize to the `languages:` list form regardless of which form the file currently uses.
|
|
29
|
+
|
|
30
|
+
## Step B — Auto-detect candidate languages
|
|
31
|
+
|
|
32
|
+
Use `Glob` (or `mcp__serena__find_file`) to detect languages present in the repo. Map common file signals to Serena language identifiers (e.g. `*.py`/`pyproject.toml` → `python`, `*.ts`/`*.tsx`/`*.js`/`package.json` → `typescript`, `*.go`/`go.mod` → `go`, `*.rs`/`Cargo.toml` → `rust`, `*.sh`/`*.bash` → `bash`, `*.md` → `markdown`, `*.yml`/`*.yaml` → `yaml`, `*.toml` → `toml`, `*.tf` → `terraform`, etc.). Use judgment — the goal is a useful suggestion, not exhaustive matching.
|
|
33
|
+
|
|
34
|
+
Collect matches into `DETECTED_LANGUAGES`. Compute `SUGGESTED = DETECTED_LANGUAGES − CURRENT_LANGUAGES`.
|
|
35
|
+
|
|
36
|
+
For the full list of valid Serena language identifiers (to avoid writing an unsupported value), see https://oraios.github.io/serena/01-about/020_programming-languages.html or the `Language` enum in https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py.
|
|
37
|
+
|
|
38
|
+
Print a plain-text summary to the user, e.g.:
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
Currently configured: bash
|
|
42
|
+
Detected in repo but not configured: typescript, markdown, yaml
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
If `SUGGESTED` is empty, just print the first line.
|
|
46
|
+
|
|
47
|
+
## Step C — Ask the user what to change
|
|
48
|
+
|
|
49
|
+
Issue **one** `AskUserQuestion` (single-select, `multiSelect: false`):
|
|
50
|
+
|
|
51
|
+
> Do you want to add or remove any languages?
|
|
52
|
+
|
|
53
|
+
Offer at least these options:
|
|
54
|
+
- `Add suggested` — only shown when `SUGGESTED` is non-empty; label it with the suggested languages, e.g. "Add typescript, markdown, yaml".
|
|
55
|
+
- `Add / remove custom` — user will supply a free-text list in the next prompt.
|
|
56
|
+
- `No changes` — abort without writing.
|
|
57
|
+
|
|
58
|
+
**Required languages**: `markdown`, `python`, `typescript`, and `yaml` are always required. They must always be present in `FINAL` regardless of what the user requests. After computing `FINAL`, silently union it with `{markdown, python, typescript, yaml}` before writing. If the user tried to remove one of these four, note it: `Note: markdown, python, typescript, yaml are required and cannot be removed.`
|
|
59
|
+
|
|
60
|
+
If the user picks `Add suggested`, set `FINAL = CURRENT_LANGUAGES ∪ SUGGESTED`.
|
|
61
|
+
|
|
62
|
+
If the user picks `Add / remove custom`, ask ONE follow-up `AskUserQuestion` with `multiSelect: false` and an `Other` free-text affordance, phrased:
|
|
63
|
+
> List languages to add and/or remove. Prefix removals with `-` (e.g. `go, rust, -bash`).
|
|
64
|
+
|
|
65
|
+
Parse the reply: tokens without `-` are additions, tokens with `-` are removals. Compute `FINAL = (CURRENT_LANGUAGES ∪ ADDITIONS) − REMOVALS`, then union with the required set.
|
|
66
|
+
|
|
67
|
+
If the user picks `No changes`, stop without writing.
|
|
68
|
+
|
|
69
|
+
If `FINAL` is empty after enforcing required languages (which cannot happen since required set is non-empty), abort.
|
|
70
|
+
|
|
71
|
+
If any token in `FINAL` is not a valid Serena identifier (per the linked reference), warn the user and abort rather than writing an unsupported value.
|
|
72
|
+
|
|
73
|
+
## Step D — Confirm and write
|
|
74
|
+
|
|
75
|
+
1. Show the proposed `FINAL` list (sorted alphabetically, with required languages clearly marked) and confirm via one final `AskUserQuestion` (`Yes, write the file` / `No, abort without writing`).
|
|
76
|
+
2. If confirmed, `Edit` `.serena/project.yml`. Use **only** this exact YAML format for the languages block — no flow-style, no quotes unless the value requires them:
|
|
77
|
+
```yaml
|
|
78
|
+
languages:
|
|
79
|
+
- lang1
|
|
80
|
+
- lang2
|
|
81
|
+
```
|
|
82
|
+
- If the file has a singular `language: <value>` line, replace it with the above block containing `FINAL` sorted alphabetically.
|
|
83
|
+
- If the file has an existing `languages:` block (list or `[]`), replace the entire block (key + all list items) with the new sorted list.
|
|
84
|
+
- Preserve everything else in the file byte-for-byte. Validate mentally that the result is valid YAML before writing: each list item on its own line, indented with exactly two spaces, starting with `- `.
|
|
85
|
+
3. Print:
|
|
86
|
+
```
|
|
87
|
+
Updated .serena/project.yml — languages: [a, b, c]
|
|
88
|
+
```
|
|
89
|
+
4. Remind the user to restart the Serena MCP:
|
|
90
|
+
```
|
|
91
|
+
Run `claude mcp restart serena` (or the equivalent for your Claude Code version) to pick up the new language list.
|
|
92
|
+
```
|
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: simplify
|
|
3
|
+
description: Analyze files or directories to remove redundancy and simplify complexity
|
|
4
|
+
category: executing
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
argument-hint: "[relative_path]"
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
|
+
|
|
12
|
+
**Purpose**: Analyze files or directories to remove redundant information and simplify overly complex structures.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Workflow
|
|
17
|
+
|
|
18
|
+
### 1. Path Validation
|
|
19
|
+
- Accept a relative path parameter (file or directory)
|
|
20
|
+
- Validate that the path exists
|
|
21
|
+
- Determine if path is a file or directory
|
|
22
|
+
|
|
23
|
+
### 2. If Directory: List Contents
|
|
24
|
+
- Use MCP Serena `list_dir` to list all files (non-recursive initially)
|
|
25
|
+
- Display file list with file types and sizes
|
|
26
|
+
- Ask user to confirm which files to analyze:
|
|
27
|
+
- All files in directory
|
|
28
|
+
- Specific file types (e.g., only .md files)
|
|
29
|
+
- Specific files from the list
|
|
30
|
+
- Recursive (include subdirectories)
|
|
31
|
+
|
|
32
|
+
### 3. File Analysis Phase
|
|
33
|
+
|
|
34
|
+
For each file in scope:
|
|
35
|
+
|
|
36
|
+
#### 3.1 Read & Categorize
|
|
37
|
+
- Use MCP Serena to read file contents
|
|
38
|
+
- Identify file type (code, docs, config, etc.)
|
|
39
|
+
- Assess file size and complexity
|
|
40
|
+
|
|
41
|
+
#### 3.2 Identify Redundancies
|
|
42
|
+
- **Duplicate Content**: Look for repeated sections, paragraphs, or code blocks
|
|
43
|
+
- **Outdated Information**: Check for conflicting or superseded information
|
|
44
|
+
- **Over-Documentation**: Identify overly verbose explanations
|
|
45
|
+
- **Dead Code**: Find unused imports, functions, or variables (for code files)
|
|
46
|
+
- **Redundant Comments**: Locate comments that just restate the code
|
|
47
|
+
|
|
48
|
+
#### 3.3 Identify Complexity
|
|
49
|
+
- **Overly Nested Structures**: Deep nesting in docs or code
|
|
50
|
+
- **Long Functions/Sections**: Files or sections that should be split
|
|
51
|
+
- **Unclear Organization**: Poor structure or flow
|
|
52
|
+
- **Excessive Abstraction**: Over-engineered solutions (violates YAGNI)
|
|
53
|
+
- **Inconsistent Formatting**: Mixed styles or conventions
|
|
54
|
+
|
|
55
|
+
### 4. Proposal Phase
|
|
56
|
+
|
|
57
|
+
For each file with issues:
|
|
58
|
+
- **Summarize findings**:
|
|
59
|
+
- Number of redundancies found
|
|
60
|
+
- Complexity issues identified
|
|
61
|
+
- Estimated reduction in file size/complexity
|
|
62
|
+
- **Propose specific changes**:
|
|
63
|
+
- List each redundancy with line numbers
|
|
64
|
+
- Suggest structural improvements
|
|
65
|
+
- Highlight what will be removed/simplified
|
|
66
|
+
- **Ask for confirmation** before proceeding
|
|
67
|
+
|
|
68
|
+
### 5. Execution Phase
|
|
69
|
+
|
|
70
|
+
With user approval:
|
|
71
|
+
- Use MCP Serena symbolic or file-based editing tools
|
|
72
|
+
- Apply changes file by file
|
|
73
|
+
- Show diff/summary of changes made
|
|
74
|
+
- Mark each file as complete
|
|
75
|
+
|
|
76
|
+
### 6. Verification Phase
|
|
77
|
+
|
|
78
|
+
After changes:
|
|
79
|
+
- For code files:
|
|
80
|
+
- Run appropriate quality gates (mypy, typecheck) from `.docs/agent/quality-gates.md`
|
|
81
|
+
- Ensure no functionality broken
|
|
82
|
+
- For documentation:
|
|
83
|
+
- Verify all critical information retained
|
|
84
|
+
- Check links and references still valid
|
|
85
|
+
- Provide summary report:
|
|
86
|
+
- Files modified
|
|
87
|
+
- Total lines removed
|
|
88
|
+
- Complexity improvements
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## Special Handling by File Type
|
|
93
|
+
|
|
94
|
+
### Code Files (.py, .ts, .tsx)
|
|
95
|
+
- Use MCP Serena symbolic tools for analysis
|
|
96
|
+
- Check for:
|
|
97
|
+
- Unused imports
|
|
98
|
+
- Dead code
|
|
99
|
+
- Duplicate functions
|
|
100
|
+
- Over-complex logic that violates KISS
|
|
101
|
+
- Premature abstractions that violate YAGNI
|
|
102
|
+
- Ensure quality gates pass after changes
|
|
103
|
+
|
|
104
|
+
### Documentation Files (.md)
|
|
105
|
+
- Check for:
|
|
106
|
+
- Duplicate sections
|
|
107
|
+
- Outdated information
|
|
108
|
+
- Overly verbose explanations
|
|
109
|
+
- Broken or redundant links
|
|
110
|
+
- Inconsistent formatting
|
|
111
|
+
- Preserve critical information and structure
|
|
112
|
+
|
|
113
|
+
### Configuration Files (.json, .yaml, .toml)
|
|
114
|
+
- Check for:
|
|
115
|
+
- Duplicate keys
|
|
116
|
+
- Unused configurations
|
|
117
|
+
- Overly complex structures
|
|
118
|
+
- Comments that could be simplified
|
|
119
|
+
- Be conservative - only remove clearly unused items
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## Multi-File Simplification
|
|
125
|
+
|
|
126
|
+
When analyzing multiple files in a directory, actively look for opportunities to **combine, merge, and delete** files while preserving all critical information.
|
|
127
|
+
|
|
128
|
+
### Combining Related Files
|
|
129
|
+
|
|
130
|
+
**When to combine**:
|
|
131
|
+
- Multiple small files covering the same topic
|
|
132
|
+
- Files that are always used together
|
|
133
|
+
- Split files with no clear separation of concerns
|
|
134
|
+
- Files with significant overlap in content
|
|
135
|
+
|
|
136
|
+
**Process**:
|
|
137
|
+
1. Identify files that could be combined
|
|
138
|
+
2. Analyze content overlap and relationships
|
|
139
|
+
3. Propose merge strategy (primary destination, organization, duplicates to remove)
|
|
140
|
+
4. Create combined file with improved structure
|
|
141
|
+
5. Delete source files after verification
|
|
142
|
+
|
|
143
|
+
### Merging Overlapping Content
|
|
144
|
+
|
|
145
|
+
**When to merge**:
|
|
146
|
+
- Different files documenting the same feature
|
|
147
|
+
- Duplicate getting-started guides
|
|
148
|
+
- Multiple READMEs at different levels with redundant info
|
|
149
|
+
- Configuration examples scattered across files
|
|
150
|
+
|
|
151
|
+
**Process**:
|
|
152
|
+
1. Map content across files to identify overlaps
|
|
153
|
+
2. Determine canonical location for each piece of information
|
|
154
|
+
3. Propose merge plan (primary file, cross-references, sections to consolidate)
|
|
155
|
+
4. Execute merge with user approval
|
|
156
|
+
5. Update all references and links
|
|
157
|
+
|
|
158
|
+
### Deleting Redundant Files
|
|
159
|
+
|
|
160
|
+
**Safe to delete when**:
|
|
161
|
+
- File is completely duplicated elsewhere
|
|
162
|
+
- File is outdated and superseded by newer documentation
|
|
163
|
+
- File contains only information available in other files
|
|
164
|
+
- File is a leftover from refactoring/renaming
|
|
165
|
+
|
|
166
|
+
**NEVER delete without verification**:
|
|
167
|
+
- Check for unique examples or edge cases
|
|
168
|
+
- Search for internal links pointing to the file
|
|
169
|
+
- Verify no unique configuration or data
|
|
170
|
+
- Confirm with user before deletion
|
|
171
|
+
|
|
172
|
+
**Deletion process**:
|
|
173
|
+
1. Identify potentially redundant files
|
|
174
|
+
2. For each file, verify all information exists elsewhere
|
|
175
|
+
3. Search for incoming links (grep for filename in codebase)
|
|
176
|
+
4. Propose deletion with evidence
|
|
177
|
+
5. Delete only with user approval
|
|
178
|
+
|
|
179
|
+
### Multi-File Analysis Strategy
|
|
180
|
+
|
|
181
|
+
1. **Initial Scan**: List files, categorize by type/topic, identify obvious duplicates
|
|
182
|
+
2. **Content Mapping**: Extract key topics, build topic → files matrix
|
|
183
|
+
3. **Overlap Analysis**: Compare files on same topic, calculate overlap percentage
|
|
184
|
+
4. **Consolidation Proposal**: Group related files, propose operations, calculate reduction
|
|
185
|
+
5. **User Confirmation**: Show detailed proposal with rationale and impact
|
|
186
|
+
6. **Execution**: Create merged files → verify → update references → delete redundant files
|
|
187
|
+
7. **Verification**: Check links, verify no information lost, ensure navigation clear
|
|
188
|
+
|
|
189
|
+
### Critical Information Protection
|
|
190
|
+
|
|
191
|
+
**Always preserve**:
|
|
192
|
+
- Unique code examples and snippets
|
|
193
|
+
- Specific configuration values
|
|
194
|
+
- Historical context or migration notes
|
|
195
|
+
- Warnings and caveats
|
|
196
|
+
- API contracts and interfaces
|
|
197
|
+
- Version-specific information
|
|
198
|
+
- Troubleshooting steps
|
|
199
|
+
- Known issues and workarounds
|
|
200
|
+
|
|
201
|
+
**Before deleting any file**:
|
|
202
|
+
- Run full-text search for unique phrases
|
|
203
|
+
- Check for unique code blocks
|
|
204
|
+
- Verify all examples exist elsewhere
|
|
205
|
+
- Search for incoming references
|
|
206
|
+
- Create summary of unique content (if any)
|
|
207
|
+
- **If in doubt**: Keep the file or ask the user
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## Safety Checks
|
|
212
|
+
|
|
213
|
+
- **Never delete critical information** without explicit user confirmation
|
|
214
|
+
- **Always preserve** unique examples, warnings, API contracts, active configurations
|
|
215
|
+
- **Ask before** removing entire sections, consolidating files, changing public APIs
|
|
216
|
+
- **Verify after** code compiles, documentation makes sense, links work
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## Notes
|
|
221
|
+
|
|
222
|
+
- Use MCP Serena for all file operations and code analysis
|
|
223
|
+
- Follow KISS, DRY, YAGNI principles when simplifying
|
|
224
|
+
- Be conservative - better to keep something potentially useful than delete it
|
|
225
|
+
- Focus on removing true redundancy, not just reducing size
|
|
226
|
+
- Maintain readability and clarity as primary goals
|
|
227
|
+
- For multi-file operations, always show consolidation plan before execution
|