better-dsh 0.2.5 → 0.3.0-c

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development.md

@@ -1,370 +0,0 @@
----
-title: "Subagent Driven Development — Execute plans via delegate_task subagents (2-stage review)"
-sidebar_label: "Subagent Driven Development"
-description: "Execute plans via delegate_task subagents (2-stage review)"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Subagent Driven Development
-
-Execute plans via delegate_task subagents (2-stage review).
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/software-development/subagent-driven-development` |
-| Path | `optional-skills/software-development\subagent-driven-development` |
-| Version | `1.1.0` |
-| Author | Hermes Agent (adapted from obra/superpowers) |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `delegation`, `subagent`, `implementation`, `workflow`, `parallel` |
-| Related skills | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Subagent-Driven Development
-
-## Overview
-
-Execute implementation plans by dispatching fresh subagents per task with systematic two-stage review.
-
-**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration.
-
-## When to Use
-
-Use this skill when:
-- You have an implementation plan (from the `plan` skill or user requirements)
-- Tasks are mostly independent
-- Quality and spec compliance are important
-- You want automated review between tasks
-
-**vs. manual execution:**
-- Fresh context per task (no confusion from accumulated state)
-- Automated review process catches issues early
-- Consistent quality checks across all tasks
-- Subagents can ask questions before starting work
-
-## The Process
-
-### 1. Read and Parse Plan
-
-Read the plan file. Extract ALL tasks with their full text and context upfront. Create a todo list:
-
-```python
-# Read the plan
-read_file("docs/plans/feature-plan.md")
-
-# Create todo list with all tasks
-todo([
-    {"id": "task-1", "content": "Create User model with email field", "status": "pending"},
-    {"id": "task-2", "content": "Add password hashing utility", "status": "pending"},
-    {"id": "task-3", "content": "Create login endpoint", "status": "pending"},
-])
-```
-
-**Key:** Read the plan ONCE. Extract everything. Don't make subagents read the plan file — provide the full task text directly in context.
-
-### 2. Per-Task Workflow
-
-For EACH task in the plan:
-
-#### Step 1: Dispatch Implementer Subagent
-
-Use `delegate_task` with complete context:
-
-```python
-delegate_task(
-    goal="Implement Task 1: Create User model with email and password_hash fields",
-    context="""
-    TASK FROM PLAN:
-    - Create: src/models/user.py
-    - Add User class with email (str) and password_hash (str) fields
-    - Use bcrypt for password hashing
-    - Include __repr__ for debugging
-
-    FOLLOW TDD:
-    1. Write failing test in tests/models/test_user.py
-    2. Run: pytest tests/models/test_user.py -v (verify FAIL)
-    3. Write minimal implementation
-    4. Run: pytest tests/models/test_user.py -v (verify PASS)
-    5. Run: pytest tests/ -q (verify no regressions)
-    6. Commit: git add -A && git commit -m "feat: add User model with password hashing"
-
-    PROJECT CONTEXT:
-    - Python 3.11, Flask app in src/app.py
-    - Existing models in src/models/
-    - Tests use pytest, run from project root
-    - bcrypt already in requirements.txt
-    """,
-    toolsets=['terminal', 'file']
-)
-```
-
-#### Step 2: Dispatch Spec Compliance Reviewer
-
-After the implementer completes, verify against the original spec:
-
-```python
-delegate_task(
-    goal="Review if implementation matches the spec from the plan",
-    context="""
-    ORIGINAL TASK SPEC:
-    - Create src/models/user.py with User class
-    - Fields: email (str), password_hash (str)
-    - Use bcrypt for password hashing
-    - Include __repr__
-
-    CHECK:
-    - [ ] All requirements from spec implemented?
-    - [ ] File paths match spec?
-    - [ ] Function signatures match spec?
-    - [ ] Behavior matches expected?
-    - [ ] Nothing extra added (no scope creep)?
-
-    OUTPUT: PASS or list of specific spec gaps to fix.
-    """,
-    toolsets=['file']
-)
-```
-
-**If spec issues found:** Fix gaps, then re-run spec review. Continue only when spec-compliant.
-
-#### Step 3: Dispatch Code Quality Reviewer
-
-After spec compliance passes:
-
-```python
-delegate_task(
-    goal="Review code quality for Task 1 implementation",
-    context="""
-    FILES TO REVIEW:
-    - src/models/user.py
-    - tests/models/test_user.py
-
-    CHECK:
-    - [ ] Follows project conventions and style?
-    - [ ] Proper error handling?
-    - [ ] Clear variable/function names?
-    - [ ] Adequate test coverage?
-    - [ ] No obvious bugs or missed edge cases?
-    - [ ] No security issues?
-
-    OUTPUT FORMAT:
-    - Critical Issues: [must fix before proceeding]
-    - Important Issues: [should fix]
-    - Minor Issues: [optional]
-    - Verdict: APPROVED or REQUEST_CHANGES
-    """,
-    toolsets=['file']
-)
-```
-
-**If quality issues found:** Fix issues, re-review. Continue only when approved.
-
-#### Step 4: Mark Complete
-
-```python
-todo([{"id": "task-1", "content": "Create User model with email field", "status": "completed"}], merge=True)
-```
-
-### 3. Final Review
-
-After ALL tasks are complete, dispatch a final integration reviewer:
-
-```python
-delegate_task(
-    goal="Review the entire implementation for consistency and integration issues",
-    context="""
-    All tasks from the plan are complete. Review the full implementation:
-    - Do all components work together?
-    - Any inconsistencies between tasks?
-    - All tests passing?
-    - Ready for merge?
-    """,
-    toolsets=['terminal', 'file']
-)
-```
-
-### 4. Verify and Commit
-
-```bash
-# Run full test suite
-pytest tests/ -q
-
-# Review all changes
-git diff --stat
-
-# Final commit if needed
-git add -A && git commit -m "feat: complete [feature name] implementation"
-```
-
-## Task Granularity
-
-**Each task = 2-5 minutes of focused work.**
-
-**Too big:**
-- "Implement user authentication system"
-
-**Right size:**
-- "Create User model with email and password fields"
-- "Add password hashing function"
-- "Create login endpoint"
-- "Add JWT token generation"
-- "Create registration endpoint"
-
-## Red Flags — Never Do These
-
-- Start implementation without a plan
-- Skip reviews (spec compliance OR code quality)
-- Proceed with unfixed critical/important issues
-- Dispatch multiple implementation subagents for tasks that touch the same files
-- Make subagent read the plan file (provide full text in context instead)
-- Skip scene-setting context (subagent needs to understand where the task fits)
-- Ignore subagent questions (answer before letting them proceed)
-- Accept "close enough" on spec compliance
-- Skip review loops (reviewer found issues → implementer fixes → review again)
-- Let implementer self-review replace actual review (both are needed)
-- **Start code quality review before spec compliance is PASS** (wrong order)
-- Move to next task while either review has open issues
-
-## Handling Issues
-
-### If Subagent Asks Questions
-
-- Answer clearly and completely
-- Provide additional context if needed
-- Don't rush them into implementation
-
-### If Reviewer Finds Issues
-
-- Implementer subagent (or a new one) fixes them
-- Reviewer reviews again
-- Repeat until approved
-- Don't skip the re-review
-
-### If Subagent Fails a Task
-
-- Dispatch a new fix subagent with specific instructions about what went wrong
-- Don't try to fix manually in the controller session (context pollution)
-
-## Efficiency Notes
-
-**Why fresh subagent per task:**
-- Prevents context pollution from accumulated state
-- Each subagent gets clean, focused context
-- No confusion from prior tasks' code or reasoning
-
-**Why two-stage review:**
-- Spec review catches under/over-building early
-- Quality review ensures the implementation is well-built
-- Catches issues before they compound across tasks
-
-**Cost trade-off:**
-- More subagent invocations (implementer + 2 reviewers per task)
-- But catches issues early (cheaper than debugging compounded problems later)
-
-## Integration with Other Skills
-
-### With plan
-
-This skill EXECUTES plans created by the `plan` skill:
-1. User requirements → plan → implementation plan
-2. Implementation plan → subagent-driven-development → working code
-
-### With test-driven-development
-
-Implementer subagents should follow TDD:
-1. Write failing test first
-2. Implement minimal code
-3. Verify test passes
-4. Commit
-
-Include TDD instructions in every implementer context.
-
-### With requesting-code-review
-
-The two-stage review process IS the code review. For final integration review, use the requesting-code-review skill's review dimensions.
-
-### With systematic-debugging
-
-If a subagent encounters bugs during implementation:
-1. Follow systematic-debugging process
-2. Find root cause before fixing
-3. Write regression test
-4. Resume implementation
-
-## Example Workflow
-
-```
-[Read plan: docs/plans/auth-feature.md]
-[Create todo list with 5 tasks]
-
---- Task 1: Create User model ---
-[Dispatch implementer subagent]
-  Implementer: "Should email be unique?"
-  You: "Yes, email must be unique"
-  Implementer: Implemented, 3/3 tests passing, committed.
-
-[Dispatch spec reviewer]
-  Spec reviewer: ✅ PASS — all requirements met
-
-[Dispatch quality reviewer]
-  Quality reviewer: ✅ APPROVED — clean code, good tests
-
-[Mark Task 1 complete]
-
---- Task 2: Password hashing ---
-[Dispatch implementer subagent]
-  Implementer: No questions, implemented, 5/5 tests passing.
-
-[Dispatch spec reviewer]
-  Spec reviewer: ❌ Missing: password strength validation (spec says "min 8 chars")
-
-[Implementer fixes]
-  Implementer: Added validation, 7/7 tests passing.
-
-[Dispatch spec reviewer again]
-  Spec reviewer: ✅ PASS
-
-[Dispatch quality reviewer]
-  Quality reviewer: Important: Magic number 8, extract to constant
-  Implementer: Extracted MIN_PASSWORD_LENGTH constant
-  Quality reviewer: ✅ APPROVED
-
-[Mark Task 2 complete]
-
-... (continue for all tasks)
-
-[After all tasks: dispatch final integration reviewer]
-[Run full test suite: all passing]
-[Done!]
-```
-
-## Remember
-
-```
-Fresh subagent per task
-Two-stage review every time
-Spec compliance FIRST
-Code quality SECOND
-Never skip reviews
-Catch issues early
-```
-
-**Quality is not an accident. It's the result of systematic process.**
-
-## Further reading (load when relevant)
-
-When the orchestration involves significant context usage, long review loops, or complex validation checkpoints, load these references for the specific discipline:
-
-- **`references/context-budget-discipline.md`** — Four-tier context degradation model (PEAK / GOOD / DEGRADING / POOR), read-depth rules that scale with context window size, and early warning signs of silent degradation. Load when a run will clearly consume significant context (multi-phase plans, many subagents, large artifacts).
-- **`references/gates-taxonomy.md`** — The four canonical gate types (Pre-flight, Revision, Escalation, Abort) with behavior, recovery, and examples. Load when designing or reviewing any workflow that has validation checkpoints — use the vocabulary explicitly so each gate has defined entry, failure behavior, and resumption rules.
-
-Both references adapted from gsd-build/get-shit-done (MIT © 2025 Lex Christopherson).

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/web-development/web-development-cloudflare-temporary-deploy.md

@@ -1,144 +0,0 @@
----
-title: "Cloudflare Temporary Deploy — Deploy a Worker live, no account, via wrangler --temporary"
-sidebar_label: "Cloudflare Temporary Deploy"
-description: "Deploy a Worker live, no account, via wrangler --temporary"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Cloudflare Temporary Deploy
-
-Deploy a Worker live, no account, via wrangler --temporary.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/web-development/cloudflare-temporary-deploy` |
-| Path | `optional-skills/web-development\cloudflare-temporary-deploy` |
-| Version | `1.0.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `cloudflare`, `workers`, `wrangler`, `deploy`, `temporary`, `agent`, `serverless`, `web-development` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Cloudflare Temporary Deploy Skill
-
-Deploy a Cloudflare Worker to a live `workers.dev` URL with zero account setup, using `wrangler deploy --temporary`. Cloudflare provisions a throwaway account, deploys, and prints a claim URL valid for 60 minutes; unclaimed accounts auto-delete. This gives an agent a tight write → deploy → verify loop without any OAuth, signup, or token copy-paste.
-
-This skill does NOT cover production deploys (use `wrangler login` + a permanent account for those), nor non-Worker Cloudflare products beyond the temporary-account limits below.
-
-## When to Use
-
-Load this skill when the user wants to:
-
-- **Ship agent-written code to a live URL** without first creating a Cloudflare account — "deploy this and give me a link"
-- **Iterate in a background/autonomous session** where a browser OAuth step would be a hard stop
-- **Prototype or evaluate Workers** quickly with a throwaway, claimable target
-- **Build a self-verifying deploy loop** — deploy, `curl` the live URL, confirm output matches the code, redeploy
-
-## When NOT to Use
-
-- **Production or CI/CD** → use a permanent account (`wrangler login` or `CLOUDFLARE_API_TOKEN`). `--temporary` errors out if any credential is present.
-- **Wrangler is already authenticated** → `--temporary` returns an error by design. Run `wrangler logout` first only if the user explicitly wants a throwaway deploy.
-- **Long-lived hosting** → temporary deployments are deleted after 60 minutes unless claimed.
-
-## Prerequisites
-
-- **Wrangler 4.102.0 or later.** This is the version that introduced `--temporary`. Earlier versions do not have it. Verify with `npx wrangler@latest --version`.
-- **Node 18+ / npm** (or `npx`, `yarn`, `pnpm`). No global install needed — `npx wrangler@latest` works.
-- **No Cloudflare credentials present.** `--temporary` only works when Wrangler is unauthenticated: no OAuth login, no `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_API_KEY` env var, no `~/.wrangler` / `~/.config/.wrangler` cached OAuth. Use the `terminal` tool's environment as-is; do not set those vars.
-- Network egress to `cloudflare.com` and `workers.dev`.
-- Using `--temporary` accepts Cloudflare's Terms of Service and Privacy Policy.
-
-## How to Run
-
-Use the `terminal` tool for every step. Always pin the version (`wrangler@latest` or `wrangler@4.102.0` or newer) so you don't accidentally run an old global wrangler that lacks the flag.
-
-1. **Scaffold a minimal Worker** (skip if the project already exists). A Worker needs a `wrangler.toml` (or `wrangler.jsonc`) and an entry script. Minimal TypeScript example — write these with `write_file`:
-
-   `wrangler.jsonc`:
-   ```jsonc
-   {
-     "name": "hello-agent",
-     "main": "src/index.ts",
-     "compatibility_date": "2025-01-01"
-   }
-   ```
-
-   `src/index.ts`:
-   ```typescript
-   export default {
-     async fetch(): Promise<Response> {
-       return new Response("hello cloudflare");
-     },
-   };
-   ```
-
-2. **Deploy with `--temporary`** from the project directory:
-   ```
-   npx wrangler@latest deploy --temporary
-   ```
-   The proof-of-work check adds a short automatic delay. On success Wrangler prints an `Account: <name> (created)` (or `(reused)`) line, a `Claim URL`, and the live `https://<worker>.<account>.workers.dev` URL.
-
-3. **Parse the URLs** from that output. Run the helper to extract them reliably instead of eyeballing:
-   ```
-   npx wrangler@latest deploy --temporary 2>&1 | python scripts/parse_deploy_output.py
-   ```
-   (Resolve `scripts/parse_deploy_output.py` to this skill's absolute path.) It prints JSON: `{"live_url", "claim_url", "account", "account_state", "expires_minutes", "deployed"}`.
-
-4. **Verify the deploy is actually live** — do not trust the deploy log alone. `curl` the live URL and confirm the body matches what the code returns:
-   ```
-   curl -sS <live_url>
-   ```
-
-5. **Iterate.** Edit the code, redeploy with the same `npx wrangler@latest deploy --temporary`. Within the 60-minute window Wrangler reuses the cached temporary account (`Account: <name> (reused)`), so the URL stays stable. `curl` again to confirm the change.
-
-6. **Hand the claim URL to the user.** Tell them: open it within 60 minutes to keep the deployment and any resources; if they don't claim it, everything auto-deletes. Treat the claim URL as a secret — it grants ownership of the account.
-
-## Quick Reference
-
-| Step | Command |
-|---|---|
-| Check version (need 4.102.0+) | `npx wrangler@latest --version` |
-| Deploy (no account) | `npx wrangler@latest deploy --temporary` |
-| Deploy + parse URLs | `npx wrangler@latest deploy --temporary 2>&1 \| python scripts/parse_deploy_output.py` |
-| Verify live | `curl -sS <live_url>` |
-| Clear cached temp account | `npx wrangler@latest logout` |
-
-### Temporary account product limits
-
-| Product | Limit on a temporary account |
-|---|---|
-| Workers | Deploys to `workers.dev` |
-| Static Assets | Up to 1,000 files, 5 MiB each |
-| KV | Allowed |
-| D1 | 1 database, 100 MB per DB / 100 MB total |
-| Durable Objects | Allowed |
-| Hyperdrive | 2 configs, 10 connections |
-| Queues | Up to 10 |
-| SSL/TLS certs | Allowed |
-
-## Pitfalls
-
-- **`--temporary` is not in `wrangler deploy --help` and is not a global flag.** It is intentionally hidden and surfaced dynamically: when an unauthenticated `wrangler deploy` fails, Wrangler prints "rerun with `--temporary`". Don't conclude the flag is missing just because `--help` omits it — check the version instead.
-- **Old global wrangler.** A stale globally-installed `wrangler` (`< 4.102.0`) silently lacks the flag. Always invoke `npx wrangler@latest` (or a pinned `>=4.102.0`) so you control the version.
-- **Auth present → hard error.** If `wrangler login` was ever run, or `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_API_KEY` is set, `--temporary` errors. Either unset the var for this shell or `wrangler logout`. Never strip a user's real credentials without telling them.
-- **Rate limiting.** Creating temporary accounts too fast fails. Reuse the cached account (just redeploy) within the 60-minute window instead of forcing a new one; if rate-limited, wait or use a permanent account.
-- **60-minute hard expiry, not extendable.** If the deploy must outlive an hour, the user must claim it. Surface this clearly.
-- **`curl` may briefly serve the old body after a redeploy.** `workers.dev` has a short edge cache; the `(reused)` line plus a new `Current Version ID` confirm the deploy succeeded even if `curl` shows stale content for a few seconds. Re-curl, or add a cache-busting query string, before concluding a redeploy failed.
-- **Don't log the claim URL into shared transcripts as "just a link."** It is credential-equivalent.
-
-## Verification
-
-- `npx wrangler@latest --version` returns `>= 4.102.0`.
-- `npx wrangler@latest deploy --temporary` prints a `workers.dev` live URL and a `claim-preview?claimToken=` claim URL.
-- `curl -sS <live_url>` returns the exact body the Worker code produces.
-- A second deploy reports `Account: <name> (reused)` and the live URL is unchanged.
-- The parser script's self-test passes: `python scripts/parse_deploy_output.py --selftest`.