bigpowers 1.0.0

package/.gitmessage

@@ -0,0 +1,5 @@
+<type>(<scope>): <description>
+
+[body explaining the why]
+
+[footer like BREAKING CHANGE: ...]

package/.releaserc.json

@@ -0,0 +1,17 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["CHANGELOG.md", "package.json", "skills-lock.json"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# 1.0.0 (2026-05-23)
+
+
+### Bug Fixes
+
+* align Gemini CLI extension with v0.42.0 requirements ([6f2b7a4](https://github.com/danielvm-git/bigpowers/commit/6f2b7a4e91727d21c980c2b7f733810b50592f23))
+* **arch:** harden karpathy gates, token economy, and architecture mandates ([300981d](https://github.com/danielvm-git/bigpowers/commit/300981d1f892a4ecf36bc94475c3a03b5529feb6))
+* **ci:** point semantic-release at correct GitHub repository ([ee17aba](https://github.com/danielvm-git/bigpowers/commit/ee17abae150c0779aabf0c12e188919f8fbf6441))
+* **commit:** refine release mapping to match semantic-release defaults ([#9](https://github.com/danielvm-git/bigpowers/issues/9)) ([1c536e5](https://github.com/danielvm-git/bigpowers/commit/1c536e53f0ddef340025f6aa5cf9a62bd13cdfee))
+* **execute-plan, plan-work:** replace PLAN.md with RELEASE-PLAN.md ([d125789](https://github.com/danielvm-git/bigpowers/commit/d1257895679e4cb241ae7db5e0c9d62861a5a193))
+* **git:** enforce feature branching gates across all skills ([454b64a](https://github.com/danielvm-git/bigpowers/commit/454b64af33df9799c29594e5f6df879ae82199da))
+* **hooks:** harden CC regex to prevent 'type/' typos ([#10](https://github.com/danielvm-git/bigpowers/issues/10)) ([ff13689](https://github.com/danielvm-git/bigpowers/commit/ff1368999f02c813b77a3a3362407efdccb3097c))
+* **karpathy.feature:** correct formatting and remove extraneous text from compliance feature ([4390ef0](https://github.com/danielvm-git/bigpowers/commit/4390ef0ecc7fc7b22bc3f5bb240657a9d61c1f82))
+* **skills:** rename to fix-report and try to trigger discovery ([7a83eb7](https://github.com/danielvm-git/bigpowers/commit/7a83eb7206a521edf693c40bb04054fc3be15e6b))
+* **skills:** simplify description and remove from lock for auto-discovery ([b698a58](https://github.com/danielvm-git/bigpowers/commit/b698a584d9e7f2540cbb6464e1db5841674e95ca))
+
+
+### Features
+
+* add automated bootstrap, visual dashboard, and global hook configuration ([a708e63](https://github.com/danielvm-git/bigpowers/commit/a708e63d79b96ec7cff14c2519bdab985d8f76a1))
+* add local installation script and project-specific lockfile support ([d49d107](https://github.com/danielvm-git/bigpowers/commit/d49d107c92258a890510ca08fe7295fcc60a5674))
+* add prepare-semantic-commit skill ([59ffddc](https://github.com/danielvm-git/bigpowers/commit/59ffddc877c80a8aa00d0d851a795011db0efa89))
+* **agent:** add stream continuity guards to prevent idle timeouts ([#14](https://github.com/danielvm-git/bigpowers/issues/14)) ([977c388](https://github.com/danielvm-git/bigpowers/commit/977c388d32c13c98eaf055438892e371342aa913))
+* **audit:** implement agentic gherkin compliance harness ([#2](https://github.com/danielvm-git/bigpowers/issues/2)) ([e4e8dec](https://github.com/danielvm-git/bigpowers/commit/e4e8decd9a90b432470ca74fa6182559ffe71dd3))
+* **audit:** implement evidence scripts ([bd9006e](https://github.com/danielvm-git/bigpowers/commit/bd9006e3ef0583f0668ff8c8188dbe7456602572))
+* **commit:** add advanced CC patterns and verification gate ([#7](https://github.com/danielvm-git/bigpowers/issues/7)) ([adc9552](https://github.com/danielvm-git/bigpowers/commit/adc955204aa219a181eced8a84a6c2a3fd7f08a4))
+* **compliance:** enforce Conventional Commits and SemVer in CONVENTIONS.md ([e590955](https://github.com/danielvm-git/bigpowers/commit/e590955fda914061ed2d4bf4387682d36497fd91))
+* **compliance:** restore lifecycle discipline and retroactive plans ([281254c](https://github.com/danielvm-git/bigpowers/commit/281254c8adef239d3f4022a318410f2bececadfb))
+* **core:** add initial project structure and configuration ([5a1feab](https://github.com/danielvm-git/bigpowers/commit/5a1feabc2060061cf0690c382edd6441427405ea))
+* **develop-tdd:** bake 'Commit-on-Green' requirement into the TDD loop ([8cbeec6](https://github.com/danielvm-git/bigpowers/commit/8cbeec66972b5651ad08a1d96a319aec53083543))
+* **guard:** implement PreToolUse hook for Conventional Commits & main-branch protection ([7ffda7c](https://github.com/danielvm-git/bigpowers/commit/7ffda7c2a2199b46372c5447079517814bf9597a))
+* **kickoff:** harden git-worktree lifecycle and automated cleanup ([8082213](https://github.com/danielvm-git/bigpowers/commit/808221382d99240c71cb5a93da8e968c0778fe06))
+* **opencode:** automate opencode.json and AGENTS.md generation ([#13](https://github.com/danielvm-git/bigpowers/issues/13)) ([598e177](https://github.com/danielvm-git/bigpowers/commit/598e177cb345ad450ac237ab08d8986ff850699a))
+* refactor to bigpowers — 38 spec-driven lifecycle skills ([f0d37af](https://github.com/danielvm-git/bigpowers/commit/f0d37afbd3c3b1ffe26bc434dc5ca79befd7add2))
+* **release:** align with semantic-release and semver ([#8](https://github.com/danielvm-git/bigpowers/issues/8)) ([9836881](https://github.com/danielvm-git/bigpowers/commit/9836881e7089d10498097e9ff29fae4c7928056b))
+* **session-state:** implement git metadata sync and finalize v1.9.0 plan ([e114514](https://github.com/danielvm-git/bigpowers/commit/e1145149dea152310568fc435a27b9d88c2fd43a))
+* **skill:** add write-document with BMAD principles and context circuit breakers ([548c2bd](https://github.com/danielvm-git/bigpowers/commit/548c2bdda214b67585af36deedbc46dc7e1b3954))
+* **skills:** add fix-and-report skill ([c3f624b](https://github.com/danielvm-git/bigpowers/commit/c3f624bd73be261fd5b876ab18c95af11e8e5e95))
+* **skills:** add stream continuity guards to output-heavy skills ([#11](https://github.com/danielvm-git/bigpowers/issues/11)) ([8c7a823](https://github.com/danielvm-git/bigpowers/commit/8c7a823885560ac141e7643e86480c4703775fd7))
+* **skills:** add test-skill to debug discovery ([acbf545](https://github.com/danielvm-git/bigpowers/commit/acbf5450e8ea274ca70ce92410b7b999df3ae7e8))
+* **skills:** consolidate redundant skills and add release planning chain ([#3](https://github.com/danielvm-git/bigpowers/issues/3)) ([40825e3](https://github.com/danielvm-git/bigpowers/commit/40825e340a95f8b0fee7fdcc1ca3da0bfbdd2b6c))
+* **skills:** implement HARD-GATE callout blocks for critical execution points ([31bed65](https://github.com/danielvm-git/bigpowers/commit/31bed65b5cfb55dccbd6eb57461377fcefddc7ea))
+* **skills:** introduce Discovery Mandate, Visual Slices, and The Gatekeeper guardrails ([1106f6a](https://github.com/danielvm-git/bigpowers/commit/1106f6ae9b0544e7e98dcbef593fece4c9d6a295))
+* **skills:** optimize fix-report skill for agent performance ([a9cae87](https://github.com/danielvm-git/bigpowers/commit/a9cae87d92d41f7c8d460873ad4e8344f259330a))
+* **skills:** register fix-and-report in manifest and README ([b9ebdb1](https://github.com/danielvm-git/bigpowers/commit/b9ebdb1e53d026bb50cf4182267bc4fc4697a690))
+* **survey:** introduce map-codebase skill for high-fidelity surveying ([6d26e2f](https://github.com/danielvm-git/bigpowers/commit/6d26e2f5d438f6119a9ae8bf0666aeaf90a81e6d))
+* update .gitignore and enhance README for clarity on agent skills ([fa21c8c](https://github.com/danielvm-git/bigpowers/commit/fa21c8cdc6bdb3a787e89d84c01ed4dbd8422e97))
+* **utility:** introduce session-state and harden process gates ([8fa8524](https://github.com/danielvm-git/bigpowers/commit/8fa85248eba2a6c0c1d95566dc5883fe60f24458))
+* **v1.12.0:** harden compliance harness and remediate Clean Code Chapter 17 ([09a5429](https://github.com/danielvm-git/bigpowers/commit/09a5429d9ac57157240fedf8e829044efeb8c9c1))
+* **v1.12.1:** harden CONVENTIONS.md with 10 missing Clean Code heuristics ([#4](https://github.com/danielvm-git/bigpowers/issues/4)) ([a6bf36a](https://github.com/danielvm-git/bigpowers/commit/a6bf36a291fe0b005988ca8d72577da0f08d5649))
+* **v1.13.0:** add harness falsification suite and npm run compliance ([#5](https://github.com/danielvm-git/bigpowers/issues/5)) ([501e98b](https://github.com/danielvm-git/bigpowers/commit/501e98b4d67e270c19c04a57c72380b2f44fb64f))
+* **v1.14.0:** add Karpathy behavioral mandates and evidence scripts ([6207082](https://github.com/danielvm-git/bigpowers/commit/6207082340f3f2c9b42422db85538f7fed3ad182))
+* **v1.14.0:** add Karpathy behavioral mandates to planning and execution skills ([42b1456](https://github.com/danielvm-git/bigpowers/commit/42b1456fc9d1498326924b45da363119faecfb9b))
+* **v1.15.0:** add Superpowers gates and evidence scripts ([3cdd81a](https://github.com/danielvm-git/bigpowers/commit/3cdd81abb27433aea77b1cf3b5b03657eb2c7b22))
+* **v1.16.0:** add testing mandates and evidence scripts ([ba7d054](https://github.com/danielvm-git/bigpowers/commit/ba7d054d9724b0866c0279fa8992061a451d2212))
+* **v1.17.0:** add guardrails - zoom-out mandate and surgical-changes discipline ([c2ee71b](https://github.com/danielvm-git/bigpowers/commit/c2ee71bd92d23ea072e6579c2462681287f2a39a))
+* **v1.18.0:** wire decision logging and minimal brief discipline into execution loop ([9619068](https://github.com/danielvm-git/bigpowers/commit/9619068e0fea068572b5c84d404e42bae64d639a))
+* **v2.0.0:** add reference library and orchestrate skill ([bc9b437](https://github.com/danielvm-git/bigpowers/commit/bc9b43767ed8087c8ee53de09be6ba8f0031c26c))
+* **v2.0.0:** complete orchestration framework and reference library ([a303c64](https://github.com/danielvm-git/bigpowers/commit/a303c64e8abfc6074f767b40938717120ad7763d))
+* **workflow:** implement verification-first loop and remove AI attribution ([#15](https://github.com/danielvm-git/bigpowers/issues/15)) ([8286ef3](https://github.com/danielvm-git/bigpowers/commit/8286ef32d6104be06f0af75d53247790594e8f3d))
+* **workflow:** mandate bigpowers skill usage and prevent direct coding ([ebf539e](https://github.com/danielvm-git/bigpowers/commit/ebf539e928512ab6f97fb958961e1a8b424acc50))

package/CLAUDE.md

@@ -0,0 +1,61 @@
+# bigpowers — Claude Code
+
+Read CONVENTIONS.md before any GitHub or git operation.
+
+## Project
+
+bigpowers — 44 agent skills for spec-driven, test-first software development by solo developers.
+Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code, Cursor, Gemini CLI)
+
+## Commands
+
+| Action | Command |
+|--------|---------|
+| Run    | `bash scripts/sync-skills.sh` |
+| Test   | N/A (documentation project) |
+| Build  | `bash scripts/install.sh` |
+| Lint   | `bash scripts/sync-skills.sh` (validates SKILL.md syntax) |
+
+## Architecture
+
+Collection of 44 verb-noun skills, each with a SKILL.md source file and supporting documentation. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning and spec output goes to specs/ at the project root.
+
+## Conventions
+
+- Skill directories use verb-noun naming (two words, kebab-case)
+- Every skill has a single SKILL.md file as its source of truth
+- All planning/spec output goes to specs/ at project root
+- Artifacts in .cursor/rules and .gemini/ are auto-generated; edit SKILL.md, not artifacts
+- Run sync-skills.sh after any SKILL.md changes to regenerate artifacts
+
+## Never
+
+- Never edit .cursor/rules or .gemini/extensions/ directly — these are generated files
+- Never create a skill without a SKILL.md file and proper verb-noun naming
+- Never push changes without running sync-skills.sh first
+
+## Token Management
+
+- **Auto-Terse**: When a session exceeds 20 turns or the context window feels "heavy" (latency increasing), you MUST switch to `terse-mode` to save tokens.
+- **Context Compaction**: Every 10 turns, summarize the current session state and implementation decisions into a short, high-density note.
+- **Minimal Output**: Prefer text-only output for simple status; use `web_fetch` or `run_shell_command` only for evidence.
+- **Stream Stability**: When writing large files or long documents, output continuously in chunks of ~200 lines. Do not pause. If you need time to process, emit a placeholder comment rather than going silent.
+
+## Session Start
+
+Before any task, run this sequence — not optional:
+
+1. Read `CLAUDE.md` (this file)
+2. Read `CONVENTIONS.md`
+3. Read `specs/STATE.md` if it exists — current milestone and pending work
+4. Read `specs/RELEASE-PLAN.md` if it exists — active release context
+
+## Agent Rules
+
+- **Workflow Mandate:** You MUST use the bigpowers skills (e.g., `plan-work`, `develop-tdd`, `craft-skill`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
+- Read specs/ and CONVENTIONS.md before writing code.
+- Write the minimum code that solves the stated problem. Nothing extra.
+- Never refactor, rename, or reorganize code outside the task scope.
+- Run tests after every change. Show evidence before declaring done.
+- One clarifying question beats a wrong assumption baked into 200 lines.
+- All written output (plans, specs, investigations) goes in specs/.

package/CONVENTIONS.md

@@ -0,0 +1,140 @@
+# Conventions
+
+## Conventional Commits & Semantic Versioning
+
+All changes to this repository MUST follow the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification. Versioning MUST strictly adhere to [Semantic Versioning 2.0.0](https://semver.org/).
+
+### Commit Message Format
+`<type>(<scope>): <description>` (Space after colon is MANDATORY)
+
+### Types & Version Bumps
+- `feat`: Minor (x.Y.z) - New feature
+- `fix`: Patch (x.y.Z) - Bug fix
+- `perf`: Patch (x.y.Z) - Performance improvement
+- `docs`, `chore`, `style`, `refactor`, `test`: No bump (unless breaking)
+- `BREAKING CHANGE:` (or `!` after type): Major (X.y.z)
+
+## GitHub & Git Operations
+
+- No direct work on `main` or `master`. Every task MUST start with a feature branch or worktree via `kickoff-branch`.
+- Use `gh pr create` not `git push` + manual PR
+- Use `gh repo clone` not `git clone` for GitHub repos
+- Use `gh run view` / `gh run watch` for CI status
+- Verify auth with `gh auth status` before operations
+- **Git Attribution:** NEVER include `Co-authored-by`, `Co-Authored-By`, or any other footer that attributes code to an AI agent (e.g., Claude, Gemini). All commits must appear as if they were authored solely by the human user.
+- Never call GitHub REST API directly (curl, fetch, etc.)
+- Never create GitHub issues from automated workflows — produce local .md files in specs/ instead
+
+## Agent Workflow Mandates
+
+**AGENTS MUST NEVER BYPASS THE BIGPOWERS WORKFLOW.**
+You are operating within the `bigpowers` spec-driven development methodology.
+- **No Direct Coding:** When a user issues a directive like "build feature X" or "go epic 10", you MUST NOT execute the request by writing code directly.
+- **Required Skills:** You MUST route all work through the appropriate bigpowers skills.
+  - Start with `survey-context` if you lack context.
+  - Use `plan-work` to generate a verifiable plan in `specs/PLAN.md` before writing any feature code.
+  - Use `develop-tdd` or `execute-plan` to implement the plan.
+  - Use `investigate-bug` for bug reports before writing a fix.
+- **Verification Mandate:** Every story implementation MUST end with a step-by-step manual verification script provided to the user. You must wait for the user to confirm behavioral correctness (UAT) before declaring the story done or moving to the next.
+- **Verification:** You MUST verify every change with tests. Code generation without a corresponding plan in `specs/` is strictly forbidden.
+- **Stream Continuity:** When writing large files or long documents, you MUST output continuously in chunks of ~200 lines. Do not pause between sections. Continue immediately until complete. If you need time to process, emit a placeholder comment or heading rather than going silent to prevent stream idle timeouts.
+
+## specs/ — All Planning Output Goes Here
+
+Every skill that produces written output writes to `specs/` at the project root:
+
+| Document | Path |
+|----------|------|
+| Domain context + ADRs | `specs/CONTEXT.md` + `specs/adr/` |
+| Domain glossary | `specs/UBIQUITOUS_LANGUAGE.md` |
+| Scope definition | `specs/SCOPE.md` |
+| Task breakdown | `specs/TASKS.md` |
+| Implementation plan | `specs/PLAN.md` (or `specs/PLAN-<feature>.md`) |
+| Refactor plan | `specs/REFACTOR.md` |
+| Spike learnings | `specs/SPIKE-<name>.md` |
+| Bug investigation | `specs/DIAGNOSIS.md` |
+| QA session log | `specs/BUG-LOG.md` |
+
+## Code Style
+
+- Functions: 4–20 lines. Split if longer.
+- Files: under 300 lines. Split by responsibility to ensure content fits within a single agent context window.
+- One thing per function, one responsibility per module (SRP).
+- Names: specific and unique. Avoid `data`, `handler`, `Manager`, `Service`. Prefer names whose grep returns < 5 hits in this codebase.
+- Types: explicit. No `any`, no untyped public functions.
+- No code duplication. Extract shared logic into a function/module.
+- Early returns over nested ifs. Max 2 levels of indentation.
+- Conditionals: expressed as positives (G29). Avoid negative flags or `unless` logic where possible.
+- The Stepdown Rule (G34): functions should descend exactly one level of abstraction.
+- Names describe side-effects (N7): if a function sends email, writes to disk, or mutates state, the name must say so (`sendWelcomeEmail`, not `processUser`).
+- No magic strings or numbers (G25): every bare string literal or numeric literal used in logic must be extracted to a named constant.
+- Boolean logic in named functions (G28): complex boolean expressions must be extracted into a named predicate function, not inlined.
+- Prefer exceptions over error codes: throw/raise an exception rather than returning a numeric or boolean error sentinel.
+- Remove dead code (G9/F4): unused functions, unreachable branches, and stale imports must be deleted — not commented out.
+- Boy Scout Rule: leave every file you touch at least as clean as you found it. Fix the first broken window you see.
+- Exception messages must include the offending value, expected shape, and an actionable remediation hint for the agent.
+- SOLID beyond SRP: favor interfaces over concrete types (DIP) when injecting dependencies.
+
+## Comments
+
+- Keep your own comments. Never strip them on refactor — they carry intent and provenance.
+- Write WHY, not WHAT.
+- Complex or non-obvious logic must include "Provenance" links (e.g., Jira issue, GitHub commit SHA, or ADR filename).
+- Docstrings on public functions: intent + one usage example.
+- Reference issue numbers / commit SHAs when a line exists because of a specific bug.
+- No obvious comments that restate the code.
+- No commented-out code (C5): dead code must be deleted, not commented out. Use git history to recover it.
+
+## Tests (F.I.R.S.T — Uncle Bob Ch 9)
+
+- Tests run headless with a single command (recorded in CLAUDE.md).
+- Every new function gets a test. Every bug fix gets a regression test.
+- Mocks for external I/O are named fake classes, not inline stubs.
+- Tests are **F**ast, **I**ndependent, **R**epeatable, **S**elf-Validating, **T**imely.
+- Never skip or @ignore a test without an explicit ambiguity note explaining what is unresolved (T4); silently ignored tests are prohibited.
+- Test boundary conditions (T5): every suite must cover exact edge values — empty input, maximum, minimum, and off-by-one.
+- Test through public interfaces only (T8): assert on observable outcomes (return values, API responses, UI state). Never assert on internal state or private methods.
+- Every change must be verifiable with a single runnable command before it is marked done.
+
+## Dependencies
+
+- Inject dependencies through constructor/parameter, not global/import.
+- Wrap third-party libs behind a thin project-owned interface.
+
+## Structure
+
+- Follow the framework convention (Rails, Django, Next.js, etc.).
+- Predictable paths: controller/model/view, src/lib/test.
+- Prefer small focused modules over god files.
+
+## Formatting
+
+- Use the language default formatter (cargo fmt, gofmt, prettier, black, rubocop -A).
+- Configured in pre-commit and on-save. No style debates beyond that.
+
+## Logging
+
+- Structured JSON for debugging / observability.
+- Plain text only for user-facing CLI output.
+
+## Defensive Code
+
+- Retry with backoff (for API/network calls in skill implementations)
+- Timeout (for long-running operations)
+- Graceful degradation (when external services/dependencies fail)
+
+The agent implements defensive code only for categories explicitly listed here.
+
+## Skill Naming — Conventions and Exceptions
+
+All skill directories use a two-word `verb-noun` kebab-case pair (ADR-0001). Grep for any skill
+name must return < 5 results across the repo.
+
+**Documented exceptions** (adjective-noun retained for clarity; renaming would reduce usability):
+
+| Skill | Convention deviation | Rationale |
+|-------|----------------------|-----------|
+| `terse-mode` | adjective-noun | `enable-terse` implies a toggle; `terse-mode` names a mode state |
+| `visual-dashboard` | adjective-noun | `view-dashboard` implies read-only; `show-dashboard` collides with `show` verbs |
+
+Any new exception requires an entry in this table before the skill is published.

package/GEMINI.md

@@ -0,0 +1,53 @@
+# bigpowers — Gemini CLI
+
+> **Auto-generated** by `sync-skills.sh` from `CLAUDE.md`. Edit CLAUDE.md, not this file.
+
+Read CONVENTIONS.md before any GitHub or git operation.
+
+## Project
+
+bigpowers — 44 agent skills for spec-driven, test-first software development by solo developers.
+Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code, Cursor, Gemini CLI)
+
+## Commands
+
+| Action | Command |
+|--------|---------|
+| Run    | `bash scripts/sync-skills.sh` |
+| Test   | N/A (documentation project) |
+| Build  | `bash scripts/install.sh` |
+| Lint   | `bash scripts/sync-skills.sh` (validates SKILL.md syntax) |
+
+## Architecture
+
+Collection of 44 verb-noun skills, each with a SKILL.md source file and supporting documentation. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning and spec output goes to specs/ at the project root.
+
+## Conventions
+
+- Skill directories use verb-noun naming (two words, kebab-case)
+- Every skill has a single SKILL.md file as its source of truth
+- All planning/spec output goes to specs/ at project root
+- Artifacts in .cursor/rules and .gemini/ are auto-generated; edit SKILL.md, not artifacts
+- Run sync-skills.sh after any SKILL.md changes to regenerate artifacts
+
+## Never
+
+- Never edit .cursor/rules or .gemini/extensions/ directly — these are generated files
+- Never create a skill without a SKILL.md file and proper verb-noun naming
+- Never push changes without running sync-skills.sh first
+
+## Token Management
+
+- **Auto-Terse**: When a session exceeds 20 turns or the context window feels "heavy" (latency increasing), you MUST switch to `terse-mode` to save tokens.
+- **Context Compaction**: Every 10 turns, summarize the current session state and implementation decisions into a short, high-density note.
+- **Minimal Output**: Prefer text-only output for simple status; use `web_fetch` or `run_shell_command` only for evidence.
+
+## Agent Rules
+
+- **Workflow Mandate:** You MUST use the bigpowers skills (e.g., `plan-work`, `develop-tdd`, `craft-skill`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
+- Read specs/ and CONVENTIONS.md before writing code.
+- Write the minimum code that solves the stated problem. Nothing extra.
+- Never refactor, rename, or reorganize code outside the task scope.
+- Run tests after every change. Show evidence before declaring done.
+- One clarifying question beats a wrong assumption baked into 200 lines.
+- All written output (plans, specs, investigations) goes in specs/.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel VM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# bigpowers — Best-in-Class Agentic Skills
+
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Version](https://img.shields.io/badge/version-1.14.0-blue.svg)
+![Skills](https://img.shields.io/badge/skills-44+-brightgreen.svg)
+
+**44+ agent skills for high-integrity, spec-driven, test-first software development by solo developers.**
+
+`bigpowers` provides a prescriptive, vertical-slice methodology for building software with AI agents (Claude Code, Gemini CLI, Cursor). It bridges the gap between raw LLM capabilities and professional engineering standards.
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/danielvm-git/bigpowers.git && cd bigpowers
+
+# 2. Install globally (links to Claude, Gemini, and Cursor)
+bash scripts/install.sh
+
+# 3. Sync artifacts
+npm run sync
+```
+
+---
+
+## 🛠 Prerequisites
+
+- **Bash**: Required for all scripts.
+- **Node.js**: Required for `npm` commands.
+- **jq**: (Highly Recommended) Used for robust configuration of tool settings.
+- **AI Tools**: One or more of:
+  - [Claude Code](https://claude.ai/code)
+  - [Gemini CLI](https://github.com/google/gemini-cli)
+  - [Cursor](https://cursor.sh/)
+
+---
+
+## 🔄 Maintenance (Update & Uninstall)
+
+### Update
+To get the latest skills and performance improvements:
+```bash
+git pull
+npm run sync
+```
+*Note: Since the installation uses symlinks, syncing automatically updates the tools.*
+
+### Uninstall
+To remove all managed symlinks and configuration hooks:
+```bash
+bash scripts/install.sh --uninstall
+```
+
+### Reinstall
+If you need a fresh start:
+```bash
+bash scripts/install.sh --uninstall && bash scripts/install.sh
+```
+
+---
+
+## 🏗 The BMAD Lifecycle
+
+Every task in `bigpowers` follows a prescriptive 5-phase arc to ensure integrity:
+
+1.  **Discover**: Investigate context, map unknowns, and survey requirements.
+2.  **Elaborate**: Formalize specs and lock design decisions (ADRs).
+3.  **Plan**: Write a verifiable, Karpathy-style implementation roadmap.
+4.  **Build**: Execute via TDD, vertical slices, and small commits.
+5.  **Sustain**: Audit quality, verify compliance, and release.
+
+---
+
+## 📖 Hierarchy of Truth
+
+| Level | Document | Responsibility |
+| :--- | :--- | :--- |
+| **Vision** | `docs/PRINCIPLES.md` | Philosophical foundations and evolution. |
+| **Context** | `specs/CONTEXT.md` | Tech stack, architecture, and glossary. |
+| **Scope** | `specs/SCOPE.md` | In-scope / out-of-scope and success criteria. |
+| **Decisions** | `specs/adr/` | Architectural Decision Records (irreversible choices). |
+| **Roadmap** | `specs/RELEASE-PLAN.md` | WSJF-prioritized releases and stories. |
+| **Current** | `specs/STATE.md` | Current milestone and session progress. |
+| **Index** | `SKILL-INDEX.md` | Canonical list of all active skills. |
+| **Style** | `CONVENTIONS.md` | Coding, testing, and naming standards. |
+
+---
+
+## 📁 Project Structure
+
+- `scripts/`: Installation, syncing, and compliance tools.
+- `specs/`: The "Brain" of your project — all planning and decisions live here.
+- `docs/references/`: Theoretical foundations (Uncle Bob, Ousterhout, Karpathy, etc.).
+- `[skill-name]/`: Source files for each of the 44+ skills.
+
+---
+
+## 🤝 References & Credits
+
+`bigpowers` stands on the shoulders of giants. It integrates patterns from:
+- **Akita**: Architectural patterns.
+- **BMAD**: Bold, Minimal, Actionable, Durable documentation.
+- **Clean Code**: Robert C. Martin (Uncle Bob).
+- **A Philosophy of Software Design**: John Ousterhout.
+- **GSD (Get Stuff Done)**: Pragmatic workflow frameworks.
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+*“Simplicity is the ultimate sophistication, but integrity is the ultimate requirement.”*

package/RELEASE.md

@@ -0,0 +1,108 @@
+# Release & Publishing Guide
+
+## Quick Start
+
+### 1. Setup (one-time)
+
+```bash
+# Add NPM_TOKEN to GitHub Secrets
+# → GitHub repo → Settings → Secrets and variables → Actions
+# → New secret: NPM_TOKEN (from npmjs.org → Access Tokens)
+
+# Commit setup
+git add .github/ .releaserc.json .gitmessage package.json package-lock.json
+git commit -m "chore: add semantic-release automation"
+git push origin main
+```
+
+### 2. Making Releases
+
+**Just commit with conventional messages:**
+
+```bash
+git commit -m "feat(new-skill): add orchestrate-project skill"
+git commit -m "fix(sync-skills): handle missing directories"
+git push origin main
+```
+
+**Automatically:**
+- ✅ Analyzes commits
+- ✅ Bumps version (semver)
+- ✅ Updates CHANGELOG.md
+- ✅ Creates git tag (v1.2.3)
+- ✅ Publishes to npm
+- ✅ Creates GitHub Release
+
+### 3. Check Release Status
+
+```bash
+# View Actions
+# GitHub → Actions → Release workflow
+
+# View published version
+npm view bigpowers
+
+# View releases
+# GitHub → Releases
+```
+
+## Commit Message Format
+
+**Required for automatic releases:**
+
+```
+feat(scope): description          # Minor version bump (1.0.0 → 1.1.0)
+fix(scope): description           # Patch version bump (1.0.0 → 1.0.1)
+docs: description                 # No version bump
+```
+
+**Examples:**
+```
+feat(skills): add new craft-skill command
+fix(sync): handle edge case in directory creation
+docs: update README with examples
+feat(develop-tdd)!: redesign test structure  # Major bump (BREAKING)
+```
+
+See `.github/CONVENTIONAL-COMMITS.md` for full format.
+
+## Manual Release (Local)
+
+```bash
+export GITHUB_TOKEN=$(gh auth token)
+export NPM_TOKEN=[from npmjs.org]
+
+npm run release
+```
+
+## Version History
+
+All releases in:
+- `CHANGELOG.md` — generated from commits
+- GitHub → Releases — GitHub release page
+- `npm view bigpowers versions` — all npm versions
+
+## Troubleshooting
+
+**No release created after push?**
+→ Commits may not follow conventional format
+→ Check Actions log: GitHub → Actions → Release workflow
+
+**"ENOAUTH" error?**
+→ Verify NPM_TOKEN in GitHub Secrets
+
+**Want to skip release for a commit?**
+→ Add `[skip ci]` in commit message:
+```
+chore: update docs [skip ci]
+```
+
+## Architecture
+
+- `.releaserc.json` — configuration
+- `.github/workflows/publish.yml` — GitHub Actions workflow
+- `.gitmessage` — commit template (optional)
+- `package.json` — version source of truth
+- `CHANGELOG.md` — auto-generated release notes
+
+See `.github/SEMANTIC-RELEASE.md` for detailed setup.