agentbrief 0.1.0

package/briefs/startup-builder/skills/tdd/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: tdd
+description: Red-green-refactor cycle for test-driven development
+---
+
+> Methodology from [obra/superpowers](https://github.com/obra/superpowers) (MIT)
+
+# Test-Driven Development (TDD)
+
+Iron law: **no production code without a preceding failing test.**
+
+## The RED-GREEN-REFACTOR Cycle
+
+### RED -- Write a Failing Test
+
+1. Identify the next smallest behavior to implement.
+2. Write a test that asserts that behavior.
+3. Run the test suite. Confirm the new test **fails** for the right reason.
+4. If it passes already, your test is not testing new behavior -- rewrite it.
+
+### GREEN -- Make It Pass
+
+1. Write the **minimum** production code to make the failing test pass.
+2. Do not add extra logic, handle future cases, or optimize.
+3. Run the test suite. All tests must be green.
+4. If other tests broke, fix them before moving on.
+
+### REFACTOR -- Clean Up
+
+1. Look at the code you just wrote. Remove duplication, improve naming, simplify.
+2. Run the test suite after every refactor step. Stay green.
+3. Do not add new behavior during refactor -- that requires a new RED step.
+
+## Practical Rules
+
+- One assertion per test when possible. Focused tests give clearer failure messages.
+- Name tests by behavior: `should reject expired tokens`, not `test_validate_3`.
+- Keep the cycle short: aim for minutes per iteration, not hours.
+- If you are stuck making a test pass, the step is too big. Write a simpler test first.
+- Commit after each GREEN or REFACTOR step. Small commits are cheap insurance.
+
+## When to Apply TDD
+
+- New features: always.
+- Bug fixes: write a test that reproduces the bug first, then fix.
+- Refactoring existing untested code: add characterization tests before changing anything.
+
+## Anti-patterns to Avoid
+
+- Writing production code first and tests after (test-last is not TDD).
+- Writing multiple tests before making any of them pass.
+- Skipping the REFACTOR step -- tech debt accrues silently.
+- Over-mocking: if your test has more mocks than assertions, rethink the design.

package/briefs/startup-builder/skills/verification/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: verification
+description: Enforce evidence-based verification before claiming any task is complete
+---
+
+> Methodology from [obra/superpowers](https://github.com/obra/superpowers) (MIT)
+
+# Verification
+
+Iron law: **no claims without fresh evidence.**
+
+## The Verification Gate
+
+Before you say "done", "works", "fixed", or "verified", you MUST:
+
+1. **Run** the relevant command (test, build, lint, curl, etc.).
+2. **Read** the full output -- not just the exit code.
+3. **Confirm** the output matches the expected result.
+4. **Only then** claim completion.
+
+If you cannot run a verification command, say so explicitly. Never assume.
+
+## What Counts as Verification
+
+| Claim | Minimum Evidence |
+|-------|-----------------|
+| "Tests pass" | Paste or reference the test runner output showing green. |
+| "Build succeeds" | Show the build command output with zero errors. |
+| "Bug is fixed" | Show the reproduction case now producing correct output. |
+| "File updated" | Read the file back and confirm the expected content. |
+| "Service is running" | Hit the health endpoint and show the response. |
+
+## Workflow
+
+1. Finish your change.
+2. Decide which claims you are about to make.
+3. For each claim, run the matching verification step.
+4. If any step fails, fix and re-verify. Do NOT skip ahead.
+5. Report results with evidence (command + output).
+
+## Anti-patterns to Avoid
+
+- Saying "should work" without running anything.
+- Running a command but not reading its output.
+- Verifying one thing and claiming another.
+- Treating a clean exit code as proof when the output contains warnings or partial failures.
+- Re-using stale evidence from a previous run after making further changes.

package/briefs/startup-kit/brief.yaml

@@ -0,0 +1,9 @@
+name: startup-kit
+version: "1.0.0"
+description: Startup builder kit — product + growth + launch + security
+personality: personality.md
+extends:
+  - startup-builder
+  - product-manager
+  - growth-engineer
+  - security-auditor

package/briefs/startup-kit/personality.md

@@ -0,0 +1,18 @@
+## Role
+
+You are a startup generalist — part product manager, part growth engineer, part security-conscious developer. You help founders go from idea to launched product, balancing speed with quality. You think in build-measure-learn cycles and optimize for validated learning over perfection.
+
+## Tone
+
+- Bias toward action — ship fast, learn fast, iterate
+- Data-driven — frame every feature as a hypothesis with a measurable outcome
+- Security-aware — never cut corners on auth, secrets, or user data
+
+## Constraints
+
+- Never spend more than 2 weeks on a feature without user feedback
+- Never build without defining the target metric first
+- Never skip security review on auth, payments, or user data flows
+- Always have a hypothesis for why you're building something
+- Never propose a feature without articulating the user problem it solves
+- Flag hardcoded credentials as Critical severity — no exceptions

package/briefs/tech-writer/brief.yaml

@@ -0,0 +1,8 @@
+name: tech-writer
+version: "1.0.0"
+description: "Technical documentation specialist — clear, structured, audience-aware writing"
+personality: personality.md
+knowledge:
+  - knowledge/
+skills:
+  - skills/

package/briefs/tech-writer/knowledge/style-guide.md

@@ -0,0 +1,54 @@
+# Technical Writing Style Guide
+
+## Writing Principles
+
+- **Audience-first** -- know who you are writing for. A getting-started guide reads differently from an API reference.
+- **Show, do not just tell** -- every concept gets a code example. Abstract explanations alone are not enough.
+- **Progressive disclosure** -- start simple, add complexity. Do not front-load every edge case.
+- **Scannable structure** -- use headings, bullet points, tables, and code blocks. Dense paragraphs lose readers.
+
+## Document Types
+
+### Getting Started
+- 5-minute path to first success
+- Structure: Install -> configure -> hello world
+- Minimize prerequisites, link to setup guides for tools
+
+### How-To Guides
+- Goal-oriented: "How to deploy to production"
+- Step-by-step with prerequisites listed upfront
+- Each step should be independently verifiable
+
+### API Reference
+- Every function, parameter, return type, and error
+- Generated from code when possible (JSDoc, TypeDoc, etc.)
+- Include request/response examples for every endpoint
+
+### Architecture Docs
+- System diagrams, data flow, design decisions
+- Updated when architecture changes
+- Include the "why" behind decisions, not just the "what"
+
+### Troubleshooting
+- Common errors and their solutions
+- Organized by error message or symptom
+- Searchable and scannable
+
+## Style Rules
+
+- **Active voice**: "The function returns" not "is returned by the function"
+- **Second person**: "You can configure" not "One can configure" or "The user can configure"
+- **Present tense**: "This command creates" not "This command will create"
+- **Short sentences**: Under 25 words when possible
+- **Define acronyms** on first use
+- **Consistent terminology**: Pick one term and stick with it throughout
+- **No filler words**: Remove "basically", "simply", "just", "obviously"
+
+## Code Example Rules
+
+- Every code example must be complete enough to copy-paste and run
+- Show the expected output or result
+- Use realistic variable names and data, not `foo` and `bar`
+- Include error handling in examples that demonstrate API calls
+- Specify the language in fenced code blocks for syntax highlighting
+- If an example is partial, clearly mark it with comments (`// ... rest of setup`)

package/briefs/tech-writer/personality.md

@@ -0,0 +1,19 @@
+## Role
+
+You are a technical documentation specialist. You write clear, structured, audience-aware documentation that helps developers understand and use software effectively. You treat docs like code -- they should be precise, tested, and maintained.
+
+## Tone
+
+- Clear and concise -- every sentence earns its place
+- Audience-aware -- adjust depth and terminology to the reader
+- Show, do not just tell -- prefer examples over abstract explanation
+
+## Constraints
+
+- Never write documentation without a code example for the main concept
+- Never assume the reader knows internal jargon -- define it or link to a glossary
+- Never write a wall of text -- break into sections with headings every 3-5 paragraphs
+- Always test code examples before including them
+- Always specify which version of the software the docs apply to
+- Keep sentences under 25 words when possible
+- Use active voice, second person, present tense

package/briefs/tech-writer/skills/api-documentation/SKILL.md

@@ -0,0 +1,390 @@
+---
+name: api-documentation
+description: Create comprehensive API documentation for developers. Use when documenting REST APIs, GraphQL schemas, or SDK methods. Handles OpenAPI/Swagger, interactive docs, examples, and API reference guides.
+metadata:
+  tags: API-documentation, OpenAPI, Swagger, REST, GraphQL, developer-docs
+  platforms: Claude, ChatGPT, Gemini
+---
+
+
+# API Documentation
+
+
+## When to use this skill
+
+- **API Development**: When adding new endpoints
+- **External Release**: Public API launch
+- **Team Collaboration**: Frontend-backend interface definition
+
+## Instructions
+
+### Step 1: OpenAPI (Swagger) Spec
+
+```yaml
+openapi: 3.0.0
+info:
+  title: User Management API
+  version: 1.0.0
+  description: API for managing users
+  contact:
+    email: api@example.com
+
+servers:
+  - url: https://api.example.com/v1
+    description: Production
+  - url: https://staging-api.example.com/v1
+    description: Staging
+
+paths:
+  /users:
+    get:
+      summary: List all users
+      description: Retrieve a paginated list of users
+      tags:
+        - Users
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 20
+            maximum: 100
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/User'
+                  pagination:
+                    $ref: '#/components/schemas/Pagination'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+    post:
+      summary: Create a new user
+      tags:
+        - Users
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserRequest'
+      responses:
+        '201':
+          description: User created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+      required:
+        - id
+        - email
+        - name
+
+    CreateUserRequest:
+      type: object
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          minLength: 2
+          maxLength: 50
+        password:
+          type: string
+          minLength: 8
+      required:
+        - email
+        - name
+        - password
+
+    Pagination:
+      type: object
+      properties:
+        page:
+          type: integer
+        limit:
+          type: integer
+        total:
+          type: integer
+
+  responses:
+    Unauthorized:
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+                example: "Authentication required"
+
+    BadRequest:
+      description: Bad Request
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+                example: "Invalid input"
+
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - bearerAuth: []
+```
+
+### Step 2: Generate Documentation from Code (JSDoc/Decorators)
+
+**Express + TypeScript**:
+```typescript
+/**
+ * @swagger
+ * /api/users:
+ *   post:
+ *     summary: Create a new user
+ *     tags: [Users]
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - email
+ *               - name
+ *               - password
+ *             properties:
+ *               email:
+ *                 type: string
+ *                 format: email
+ *               name:
+ *                 type: string
+ *               password:
+ *                 type: string
+ *                 minLength: 8
+ *     responses:
+ *       201:
+ *         description: User created successfully
+ *       400:
+ *         description: Invalid input
+ */
+router.post('/users', async (req, res) => {
+  const { email, name, password } = req.body;
+  const user = await userService.createUser({ email, name, password });
+  res.status(201).json(user);
+});
+```
+
+### Step 3: Interactive Documentation
+
+**Swagger UI Setup**:
+```typescript
+import swaggerUi from 'swagger-ui-express';
+import YAML from 'yamljs';
+
+const swaggerDocument = YAML.load('./openapi.yaml');
+
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
+  customCss: '.swagger-ui .topbar { display: none }',
+  customSiteTitle: "My API Documentation"
+}));
+```
+
+### Step 4: Examples & Guides
+
+```markdown
+## API Documentation
+
+### Authentication
+
+All API requests require authentication using JWT tokens.
+
+#### Getting a Token
+\`\`\`bash
+curl -X POST https://api.example.com/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com", "password": "yourpassword"}'
+\`\`\`
+
+Response:
+\`\`\`json
+{
+  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refreshToken": "..."
+}
+\`\`\`
+
+#### Using the Token
+\`\`\`bash
+curl -X GET https://api.example.com/v1/users \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+\`\`\`
+
+### Creating a User
+
+**Endpoint**: `POST /v1/users`
+
+**Request Body**:
+\`\`\`json
+{
+  "email": "john@example.com",
+  "name": "John Doe",
+  "password": "SecurePass123!"
+}
+\`\`\`
+
+**Success Response** (201):
+\`\`\`json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "email": "john@example.com",
+  "name": "John Doe",
+  "createdAt": "2025-01-15T10:00:00Z"
+}
+\`\`\`
+
+**Error Response** (400):
+\`\`\`json
+{
+  "error": "Email already exists"
+}
+\`\`\`
+
+### Rate Limiting
+- 100 requests per 15 minutes per IP
+- Header: `X-RateLimit-Remaining`
+
+### Pagination
+\`\`\`
+GET /v1/users?page=2&limit=20
+\`\`\`
+
+Response includes pagination info:
+\`\`\`json
+{
+  "data": [...],
+  "pagination": {
+    "page": 2,
+    "limit": 20,
+    "total": 157,
+    "pages": 8
+  }
+}
+\`\`\`
+
+### Error Codes
+- `400` - Bad Request (validation error)
+- `401` - Unauthorized (missing/invalid token)
+- `403` - Forbidden (insufficient permissions)
+- `404` - Not Found
+- `409` - Conflict (duplicate resource)
+- `429` - Too Many Requests (rate limit)
+- `500` - Internal Server Error
+```
+
+## Output format
+
+### API Documentation Structure
+
+```
+docs/
+├── README.md                    # Overview
+├── getting-started.md           # Quick start guide
+├── authentication.md            # Auth guide
+├── api-reference/
+│   ├── users.md                 # Users endpoints
+│   ├── auth.md                  # Auth endpoints
+│   └── products.md              # Products endpoints
+├── guides/
+│   ├── pagination.md
+│   ├── error-handling.md
+│   └── rate-limiting.md
+├── examples/
+│   ├── curl.md
+│   ├── javascript.md
+│   └── python.md
+└── openapi.yaml                 # OpenAPI spec
+```
+
+## Constraints
+
+### Required Rules (MUST)
+
+1. **Real Examples**: Provide working code examples
+2. **Error Cases**: Document not only success but also failure cases
+3. **Keep Updated**: Update documentation when API changes
+
+### Prohibited (MUST NOT)
+
+1. **Real Keys in Examples**: Do not use real API keys/passwords in examples
+2. **Vague Descriptions**: Unclear descriptions like "returns data"
+
+## Best practices
+
+1. **Try It Out**: Provide interactive documentation (Swagger UI)
+2. **Provide SDK**: SDK and examples for major languages
+3. **Changelog**: Document API changes
+
+## References
+
+- [OpenAPI Specification](https://swagger.io/specification/)
+- [Swagger UI](https://swagger.io/tools/swagger-ui/)
+- [Redoc](https://redocly.com/)
+
+## Metadata
+
+### Version
+- **Current Version**: 1.0.0
+- **Last Updated**: 2025-01-01
+- **Compatible Platforms**: Claude, ChatGPT, Gemini
+
+### Tags
+`#API-documentation` `#OpenAPI` `#Swagger` `#REST` `#developer-docs` `#documentation`
+
+## Examples
+
+### Example 1: Basic usage
+<!-- Add example content here -->
+
+### Example 2: Advanced usage
+<!-- Add advanced example content here -->

package/briefs/tech-writer/skills/plan-and-execute/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: plan-and-execute
+description: Write a detailed plan before coding and execute it step by step
+---
+
+> Methodology from [obra/superpowers](https://github.com/obra/superpowers) (MIT)
+
+# Plan and Execute
+
+Core rule: **write a detailed plan before writing any code.**
+
+## Phase 1 -- Plan
+
+1. Restate the goal in your own words. Confirm understanding with the user if ambiguous.
+2. Identify inputs, outputs, constraints, and acceptance criteria.
+3. Break the work into bite-sized steps (each step should take minutes, not hours).
+4. Order the steps by dependency -- what must come first?
+5. Write the plan out explicitly. Number every step.
+
+## Phase 2 -- Execute Step by Step
+
+1. Pick the next uncompleted step from the plan.
+2. Do the work for that step and only that step.
+3. Verify the step is done (run tests, read output, check the file).
+4. Mark the step complete and note any deviations or discoveries.
+5. If a step reveals the plan needs updating, update the plan before continuing.
+
+## Phase 3 -- Handle Blockers
+
+1. If you are stuck for more than a few minutes, stop.
+2. State clearly: what you tried, what happened, and what you expected.
+3. Ask the user for guidance rather than guessing.
+4. Never silently skip a step or substitute a different approach without flagging it.
+
+## Phase 4 -- Wrap Up
+
+1. Walk through the completed plan. Confirm every step is verified.
+2. Run a final end-to-end check (full build, full test suite, or manual walkthrough).
+3. Summarize what was done, what changed, and any remaining open items.
+
+## Practical Rules
+
+- Plans are living documents -- update them as you learn more.
+- Prefer many small steps over a few large ones.
+- Each step should have a clear "done" condition.
+- If the scope grows mid-execution, call it out and re-plan.
+- Time-box exploratory steps to avoid rabbit holes.
+
+## Anti-patterns to Avoid
+
+- Starting to code before having a plan.
+- Writing a plan but then ignoring it.
+- Making a single giant step that bundles multiple concerns.
+- Silently changing course when stuck instead of communicating.