cyberwalk3r · cyberwalk3r · Mar 6, 2026 · Mar 6, 2026 · Mar 6, 2026 · Mar 6, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,9 +1,9 @@
 {
   "name": "qa-toolkit",
-  "version": "1.1.0",
-  "description": "Claude Code plugin for QA testers. Structured PR reviews, test case generation, bug reports, regression planning, and 6 more QA workflows. Auto-detects your tech stack. No code required.",
+  "version": "2.0.0",
+  "description": "Claude Code plugin with 15 QA skills and 3 agent personas. PR reviews, test cases, bug reports, regression plans, coverage gaps, risk analysis, and more. Auto-detects your tech stack.",
   "author": {
-    "name": "QA Skills"
+    "name": "cyberwalk3r"
   },
   "repository": {
     "type": "git",

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -18,3 +18,4 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
       - run: node --test tests/*.test.js
+      - run: node scripts/validate-skill-budget.js
diff --git a/.gitignore b/.gitignore
@@ -15,6 +15,9 @@ Thumbs.db
 desktop.ini
 ehthumbs.db
 
+# Claude Code user settings (not part of the plugin)
+.claude/
+
 # Generated at runtime in target projects
 qa-artifacts/
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,38 @@
 # Changelog
 
+## [2.0.1] — 2026-03-07
+
+### Added
+- `--dry-run` flag for `detect-project.js` — preview detection without writing files
+- Session end summary output showing promoted findings and modified artifact count
+- Skill budget validation (`validate-skill-budget.js`) added to CI pipeline
+- GitHub Pages documentation site (`docs/`)
+
+### Changed
+- Removed `.claude/settings.local.json` — plugins should not ship user-local settings; permissions are approved interactively on first use
+- Moved test files from `scripts/` to `tests/` directory
+
+### Fixed
+- README "Permissions & Side Effects" section now accurately describes interactive approval (not pre-approved settings)
+
+## [2.0.0] — 2026-03-06
+
+QA Toolkit v2.0 is a ground-up rethink of how the plugin operates. The core idea: every skill now reads your project state before producing output, so artifacts build on each other rather than starting cold every time.
+
+### Added
+- **State-aware skill system** — all skills read `.qa-context.json` on invocation, adapt output to detected stack, and write findings back so subsequent skills have context
+- **Shared references** (`skills/shared/references/`) — `context-preamble.md`, `state-integration.md`, `output-formats.md`, `artifact-organization.md` loaded by all skills to enforce consistent behavior
+- **5 new skills**: `test-plan`, `exploratory-testing`, `coverage-gap`, `risk-prioritization`, `flaky-test-diagnosis`
+- **Multi-format output** — skills produce output in the format best suited to the artifact type (Markdown reports, Gherkin, cURL/Postman/Playwright, JSON/CSV/SQL, etc.)
+- **Redesigned agents** — `qa-reviewer`, `qa-lead`, `qa-explorer` rebuilt with explicit tool restrictions, typed return contracts, and persistent memory across turns
+
+### Changed
+- **5 redesigned skills**: `e2e-test`, `bug-report`, `api-test`, `regression-planner`, `pr-review` — all updated for state-awareness and multi-format output
+- Agent personas now define tool access boundaries (not just tone), making subagent behavior predictable and composable
+
+### Fixed
+- Updated test suite to match v2 skill behavior (stale v1.x assertions removed)
+
 ## [1.1.0] — 2026-02-23
 
 ### Fixed
@@ -19,7 +52,7 @@
 - `hooksEnabled` toggle to disable hooks without removing the plugin
 - 27 automated tests using Node.js built-in test runner (zero dependencies)
 - GitHub Actions CI workflow running tests on Node 18/20/22
-- `.qa-config.json` schema documentation in README
+- `.qa-context.json` schema documentation in README
 - `.gitignore` suggestion step in setup skill workflow
 - "Permissions & Side Effects" section in README with `Bash(git:*)` mechanism explained
 - Contextual "Suggested Next Steps" cross-references in all skills

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,7 +2,7 @@
 
 ## What This Is
 
-A Claude Code plugin providing 10 QA skills (slash commands) and 3 agent personas. Auto-detects project tech stack and produces structured QA artifacts.
+A Claude Code plugin providing 15 QA skills (slash commands) and 3 agent personas. Auto-detects project tech stack and produces structured QA artifacts.
 
 ## Project Structure
 
@@ -11,7 +11,7 @@ A Claude Code plugin providing 10 QA skills (slash commands) and 3 agent persona
 settings.json               — Default agent and plugin settings
 hooks/hooks.json            — Event hooks (SessionStart, Stop)
 scripts/detect-project.js   — Auto-detection script (runs on SessionStart)
-scripts/save-artifact.js    — Activity logger (runs on Stop)
+scripts/session-hook.js     — State promotion, archival, activity logger (runs on Stop)
 agents/<name>.md            — Agent persona definitions (conversational, multi-turn)
 skills/<name>/SKILL.md      — Skill definitions (one-shot structured output)
 skills/<name>/references/   — Domain-specific knowledge files
@@ -21,9 +21,9 @@ skills/<name>/scripts/      — Helper scripts (e.g., Playwright runner)
 ## Conventions
 
 ### Skills
-- `SKILL.md` must have YAML frontmatter with `name` and `description` (one sentence)
+- `SKILL.md` must have YAML frontmatter with `name` and `description` (1-3 sentences covering what it does and when to trigger it)
 - Skills produce one-shot structured output and save to the configured output directory
-- Each skill reads `<outputDir>/.qa-config.json` for project context
+- Each skill reads `<outputDir>/.qa-context.json` for project context
 - Reference files contain non-obvious, specific guidance — not generic info
 - Include a "Suggested Next Steps" section with conditional cross-references to related skills
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,30 +1,111 @@
 # Contributing
 
+## How It All Fits Together
+
+QA Toolkit is a Claude Code plugin. It has three moving parts:
+
+- **Skills** (`skills/<name>/SKILL.md`) — one-shot slash commands that produce structured QA artifacts
+- **Agents** (`agents/<name>.md`) — conversational personas for multi-turn QA work
+- **Scripts** (`scripts/`) — Node.js hooks that run on session start/end (auto-detection, activity logging)
+
+All skills follow the **state-aware pattern**: read project context from `.qa-context.json` → adapt output to the detected stack → write findings back so the next skill has more to work with.
+
 ## How to Contribute
 
 1. Fork the repository
 2. Create a feature branch: `git checkout -b feature/your-feature`
-3. Make your changes
+3. Make your changes following the conventions below
 4. Run the test suite: `node --test tests/*.test.js`
 5. Test locally: `claude --plugin-dir ./qa-toolkit`
 6. Submit a pull request
 
 ## Adding a New Skill
 
-1. Create `skills/<skill-name>/SKILL.md` with YAML frontmatter (`name`, `description`)
-2. Add reference files in `skills/<skill-name>/references/` if needed
-3. Update README.md with the new skill
-4. Update CHANGELOG.md
+### Minimum structure
+
+```
+skills/<skill-name>/
+├── SKILL.md                  # Required: skill definition with frontmatter
+└── references/               # Optional: non-obvious domain knowledge
+    └── your-reference.md
+```
+
+### SKILL.md conventions
+
+- YAML frontmatter must have `name` and `description` (one sentence max)
+- Begin with the context preamble: load `skills/shared/references/context-preamble.md` to read project state
+- Adapt output based on detected `languages`, `frameworks`, `testFrameworks` from `.qa-context.json`
+- Save artifacts to `<outputDir>/<category>/` (read `outputDir` from `.qa-context.json`)
+- End with a "Suggested Next Steps" section with conditional cross-references to related skills
+
+### State-aware pattern
+
+Every skill should follow this flow:
+
+1. **Read state** — check if `.qa-context.json` exists; if yes, load it for stack context
+2. **Adapt output** — use detected frameworks to shape format (e.g., Jest vs Pytest syntax, Jira vs GitHub Issues format)
+3. **Write findings** — append relevant findings to a skill-specific log in `<outputDir>/` so subsequent skills have more context
+
+See `skills/shared/references/state-integration.md` for the full pattern with examples.
+
+### Reference files
+
+Put reference files in `skills/<name>/references/` only when they contain **non-obvious, specific guidance** that Claude wouldn't already know. Generic QA knowledge doesn't belong here.
+
+Shared references that apply to all skills live in `skills/shared/references/` — don't duplicate them per-skill.
 
 ## Adding a New Agent
 
-1. Create `agents/<agent-name>.md` with YAML frontmatter (`name`, `description`)
-2. Define the persona, not the workflow — workflows belong in skills
-3. Update README.md
+```
+agents/<agent-name>.md        # Required: agent definition with frontmatter
+```
+
+### Agent conventions (v2)
+
+- YAML frontmatter must have `name` and `description`
+- Define the **persona and tool access boundaries**, not the workflow — workflows belong in skills
+- Specify **tool restrictions**: which tools the agent may and may not use
+- Define a **return contract**: what the agent always returns at the end of each turn (e.g., a summary, a next-step prompt, a structured finding)
+- Agents have **persistent memory** across turns — design the persona to accumulate context, not start fresh each turn
+
+## Scripts
+
+- All scripts are Node.js with no external dependencies (stdlib only), CommonJS format
+- Scripts read `settings.json` for plugin-level config (`outputDir`, `hooksEnabled`)
+- Hook scripts run on `SessionStart` and `Stop` events
+
+## Testing
+
+```bash
+# Run tests
+node --test tests/*.test.js
+
+# Validate skill registration budget (must stay under 16K chars)
+node scripts/validate-skill-budget.js
+```
+
+Both run in CI on Node 18/20/22. Tests use Node.js built-in test runner (zero dependencies). When adding a skill or modifying a script, add or update the corresponding test in `tests/`.
+
+### Skill budget
+
+The combined character count of all skill `name` + `description` frontmatter fields must stay under 16,000 characters (Claude Code registration limit). Run `node scripts/validate-skill-budget.js` to check. The `--json` flag produces machine-readable output for CI.
+
+## Local Development
+
+```bash
+claude --debug --plugin-dir ./qa-toolkit
+```
+
+The `--debug` flag shows hook execution and skill loading in the Claude Code output.
+
+### Preview detection
+
+To see what the SessionStart hook would detect without writing any files:
+
+```bash
+node scripts/detect-project.js --dry-run
+```
 
-## Guidelines
+---
 
-- Keep SKILL.md `description` fields to one sentence
-- Reference files should contain non-obvious, specific guidance — not generic info Claude already knows
-- All generated artifacts should be saved to `qa-artifacts/<category>/`
-- Test with `claude --debug --plugin-dir ./qa-toolkit` to verify component loading
+Something missing or wrong? Open an issue — this doc is meant to stay short, not stay incomplete.
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 QA Skills
+Copyright (c) 2026 cyberwalk3r
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal