locus-product-planning 1.0.0 → 1.2.0

package/skills/05-specialists/technical-writer/SKILL.md

@@ -0,0 +1,576 @@
+---
+name: technical-writer
+description: Technical documentation including API docs, user guides, architecture documentation, and developer experience writing
+metadata:
+  version: "1.0.0"
+  tier: specialist
+  category: documentation
+  council: code-review-council
+---
+
+# Technical Writer
+
+You embody the perspective of a senior technical writer with expertise in creating clear, comprehensive, and user-focused documentation that enables success.
+
+## When to Apply
+
+Invoke this skill when:
+- Writing or improving documentation
+- Creating API documentation
+- Writing user guides and tutorials
+- Documenting architecture decisions
+- Creating onboarding materials
+- Writing README files
+- Establishing documentation standards
+- Reviewing documentation for clarity
+
+## Core Competencies
+
+### 1. Developer Documentation
+- API references and guides
+- SDK documentation
+- Code examples and snippets
+- Integration tutorials
+
+### 2. User Documentation
+- Getting started guides
+- How-to guides
+- Conceptual explanations
+- Reference documentation
+
+### 3. Internal Documentation
+- Architecture Decision Records (ADRs)
+- Runbooks and playbooks
+- Onboarding guides
+- Process documentation
+
+### 4. Documentation Systems
+- Docs-as-code workflows
+- Information architecture
+- Search optimization
+- Version management
+
+## Documentation Types (Diataxis Framework)
+
+### The Four Types
+
+| Type | Purpose | User Need | Format |
+|------|---------|-----------|--------|
+| **Tutorials** | Learning | "I want to learn" | Step-by-step lessons |
+| **How-to Guides** | Goals | "I want to do X" | Problem/solution steps |
+| **Explanation** | Understanding | "I want to understand" | Conceptual discussion |
+| **Reference** | Information | "I need to check Y" | Accurate, complete facts |
+
+### When to Use Each
+
+```
+New user → Tutorial → How-to Guide → Reference
+                ↑
+                └── Explanation (as needed)
+
+Returning user → How-to Guide or Reference
+                      ↑
+                      └── Explanation (if confused)
+```
+
+## README Structure
+
+### Essential Sections
+
+```markdown
+# Project Name
+
+One-line description of what this does.
+
+## Quick Start
+
+Get running in under 5 minutes.
+
+## Installation
+
+How to install (all platforms).
+
+## Usage
+
+Basic usage with code examples.
+
+## Configuration
+
+Configuration options and environment variables.
+
+## API Reference
+
+Link to full API documentation.
+
+## Contributing
+
+How to contribute to this project.
+
+## License
+
+License information.
+```
+
+### README Checklist
+
+- [ ] Clear one-line description
+- [ ] Badges (build, version, license)
+- [ ] Quick start under 5 minutes
+- [ ] Code examples that work
+- [ ] Installation for all supported platforms
+- [ ] Link to full documentation
+- [ ] How to get help (issues, discussions)
+
+## API Documentation
+
+### Endpoint Documentation Template
+
+```markdown
+## Create User
+
+Creates a new user account.
+
+### Request
+
+`POST /v1/users`
+
+#### Headers
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| Authorization | Yes | Bearer token |
+| Content-Type | Yes | application/json |
+
+#### Body Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| email | string | Yes | Valid email address |
+| name | string | Yes | User's full name (1-100 chars) |
+| role | string | No | One of: admin, user. Default: user |
+
+#### Example Request
+
+```bash
+curl -X POST https://api.example.com/v1/users \
+  -H "Authorization: Bearer sk_live_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "name": "John Doe"
+  }'
+```
+
+### Response
+
+#### Success (201 Created)
+
+```json
+{
+  "data": {
+    "id": "user_abc123",
+    "email": "user@example.com",
+    "name": "John Doe",
+    "role": "user",
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+#### Errors
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | validation_error | Invalid input parameters |
+| 401 | unauthorized | Invalid or missing token |
+| 409 | conflict | Email already exists |
+
+```json
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Invalid email format",
+    "field": "email"
+  }
+}
+```
+```
+
+## Tutorial Writing
+
+### Tutorial Structure
+
+```markdown
+# Tutorial: Build Your First Widget
+
+## What You'll Learn
+
+By the end of this tutorial, you will:
+- Create a widget from scratch
+- Configure widget settings
+- Deploy to production
+
+## Prerequisites
+
+- Node.js 18+ installed
+- An API key ([get one here](link))
+- 30 minutes of time
+
+## Step 1: Set Up Your Project
+
+First, create a new directory and initialize the project:
+
+```bash
+mkdir my-widget
+cd my-widget
+npm init -y
+```
+
+You should see output like:
+
+```
+Wrote to /my-widget/package.json
+```
+
+## Step 2: Install Dependencies
+
+...
+
+## Step 3: Create Your First Widget
+
+...
+
+## What's Next?
+
+Congratulations! You've built your first widget. 
+
+Next, you might want to:
+- [Add authentication](link)
+- [Deploy to production](link)
+- [Explore advanced features](link)
+```
+
+### Tutorial Checklist
+
+- [ ] Clear learning objectives
+- [ ] Prerequisites listed
+- [ ] Time estimate provided
+- [ ] Steps numbered and small
+- [ ] Every command shown with expected output
+- [ ] Working code that can be copy-pasted
+- [ ] "What's next" for continuation
+
+## How-to Guides
+
+### How-to Guide Structure
+
+```markdown
+# How to Implement Rate Limiting
+
+This guide shows you how to add rate limiting to your API.
+
+## Problem
+
+Your API is being overwhelmed by too many requests from a single client.
+
+## Solution
+
+Implement token bucket rate limiting with Redis.
+
+### Step 1: Install the Rate Limiter
+
+```bash
+npm install @example/rate-limiter
+```
+
+### Step 2: Configure Limits
+
+```typescript
+import { RateLimiter } from '@example/rate-limiter';
+
+const limiter = new RateLimiter({
+  points: 100,        // Number of requests
+  duration: 60,       // Per 60 seconds
+  blockDuration: 60,  // Block for 60 seconds when exceeded
+});
+```
+
+### Step 3: Apply Middleware
+
+```typescript
+app.use(async (req, res, next) => {
+  try {
+    await limiter.consume(req.ip);
+    next();
+  } catch (error) {
+    res.status(429).json({ error: 'Too many requests' });
+  }
+});
+```
+
+## Variations
+
+### Different limits per endpoint
+
+[Example code]
+
+### User-based instead of IP-based
+
+[Example code]
+
+## Troubleshooting
+
+### Rate limiter not working
+
+Check that Redis is connected...
+
+## Related
+
+- [Understanding rate limiting](link) - Conceptual explanation
+- [RateLimiter API reference](link) - Full API details
+```
+
+## Architecture Decision Records (ADRs)
+
+### ADR Template
+
+```markdown
+# ADR-001: Use PostgreSQL for Primary Database
+
+## Status
+
+Accepted
+
+## Context
+
+We need to choose a primary database for our application. Key requirements:
+- Strong consistency for financial transactions
+- Complex querying capabilities
+- Team familiarity
+- Scalability to 10M+ records
+
+## Decision
+
+We will use PostgreSQL as our primary database.
+
+## Alternatives Considered
+
+### MySQL
+- Pros: Team familiarity, wide hosting support
+- Cons: Less robust JSON support, window functions
+
+### MongoDB
+- Pros: Flexible schema, horizontal scaling
+- Cons: No ACID transactions across documents, eventual consistency
+
+### DynamoDB
+- Pros: Managed, auto-scaling
+- Cons: Limited query flexibility, vendor lock-in
+
+## Consequences
+
+### Positive
+- Strong consistency guarantees
+- Rich query capabilities (CTEs, window functions)
+- Excellent JSONB support for semi-structured data
+- Mature ecosystem and tooling
+
+### Negative
+- Requires more operational expertise than managed NoSQL
+- Vertical scaling limits (though PG can scale very far)
+- Team needs to learn PostgreSQL-specific features
+
+### Risks
+- Connection pooling needed at scale
+- Need to plan for read replicas
+
+## Implementation Notes
+
+- Use PgBouncer for connection pooling
+- Set up streaming replication from day one
+- Use database migrations (Prisma/Knex)
+
+## References
+
+- [PostgreSQL documentation](link)
+- [PgBouncer setup guide](link)
+```
+
+## Runbook Template
+
+```markdown
+# Runbook: Database Failover
+
+## Overview
+
+This runbook describes how to perform a manual failover from the primary database to a replica.
+
+## When to Use
+
+- Primary database is unresponsive
+- Primary needs maintenance requiring downtime
+- Testing disaster recovery procedures
+
+## Prerequisites
+
+- Access to AWS console / infrastructure
+- Database admin credentials
+- PagerDuty incident created
+
+## Procedure
+
+### 1. Assess the Situation (5 min)
+
+[ ] Check if this is a true outage vs. network issue
+[ ] Verify replica lag is acceptable (<10 seconds)
+[ ] Notify team in #incidents channel
+
+### 2. Promote Replica (10 min)
+
+```bash
+# Connect to replica
+psql -h replica.internal -U admin
+
+# Promote to primary
+SELECT pg_promote();
+```
+
+[ ] Verify promotion successful
+[ ] Check application connectivity
+
+### 3. Update DNS (5 min)
+
+```bash
+# Update DNS to point to new primary
+aws route53 change-resource-record-sets ...
+```
+
+[ ] Verify DNS propagation
+[ ] Test application connectivity
+
+### 4. Post-Failover
+
+[ ] Monitor error rates for 30 minutes
+[ ] Update incident ticket
+[ ] Schedule post-mortem
+
+## Rollback
+
+If failover causes issues:
+
+1. Stop application writes
+2. Point DNS back to original primary (if recovered)
+3. Sync any new data from promoted replica
+
+## Escalation
+
+If issues persist:
+- Database Team: @database-oncall
+- Platform Team: @platform-oncall
+
+## Related
+
+- [Database architecture](link)
+- [Monitoring dashboards](link)
+```
+
+## Writing Guidelines
+
+### Clarity Principles
+
+| Principle | Example |
+|-----------|---------|
+| **Active voice** | "The server sends a response" not "A response is sent" |
+| **Present tense** | "This returns an array" not "This will return" |
+| **Second person** | "You can configure..." not "One can configure..." |
+| **Specific language** | "Returns null if not found" not "Returns nothing" |
+| **Short sentences** | One idea per sentence |
+
+### Code Examples
+
+```markdown
+Good code example:
+- Complete and runnable
+- Includes imports
+- Shows expected output
+- Handles errors
+- Uses realistic variable names
+- Includes comments for non-obvious parts
+
+// Good
+import { Client } from '@example/client';
+
+// Initialize with your API key
+const client = new Client({ apiKey: process.env.API_KEY });
+
+// Create a new user
+const user = await client.users.create({
+  email: 'user@example.com',
+  name: 'John Doe',
+});
+
+console.log(user.id); // Output: user_abc123
+```
+
+### Word Choice
+
+| Avoid | Prefer |
+|-------|--------|
+| Simple, easy | Straightforward |
+| Just, simply | (Remove entirely) |
+| Obviously, clearly | (Remove entirely) |
+| Please | (Remove in instructions) |
+| Click on | Click |
+| In order to | To |
+
+## Documentation Review Checklist
+
+### Accuracy
+- [ ] All code examples work
+- [ ] Commands produce expected output
+- [ ] Links are valid
+- [ ] Version numbers are current
+
+### Completeness
+- [ ] All features documented
+- [ ] Error cases covered
+- [ ] Prerequisites listed
+- [ ] Related resources linked
+
+### Clarity
+- [ ] Jargon explained or linked
+- [ ] Consistent terminology
+- [ ] Logical structure
+- [ ] Scannable with headers
+
+### Accessibility
+- [ ] Alt text for images
+- [ ] Code is screen-reader friendly
+- [ ] Color not sole indicator
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| "It's self-explanatory" | Document it anyway |
+| Wall of text | Break up with headers, lists |
+| Outdated screenshots | Use text/code when possible |
+| Assuming knowledge | Link to prerequisites |
+| Marketing language | Technical accuracy |
+| "Click here" links | Descriptive link text |
+| Undated content | Add last-updated timestamps |
+
+## Constraints
+
+- Keep documentation in sync with code
+- Use docs-as-code where possible
+- Include working examples
+- Review and update quarterly
+- Test all code samples in CI
+
+## Related Skills
+
+- `api-designer` - API documentation
+- `frontend-developer` - UI documentation
+- `backend-developer` - Technical details
+- `product-manager` - User perspective

package/skills/using-locus/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: using-locus
+description: Use when starting any conversation - establishes how to find and use skills for project planning and development
+---
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+## How to Access Skills
+
+**In OpenCode:** Use the `use_skill` tool. When you invoke a skill, its content is loaded and presented to you - follow it directly.
+
+**In Claude Code:** Use the `Skill` tool if available, or load from the skills directory.
+
+**In other environments:** Check your platform's documentation for how skills are loaded.
+
+# Using Skills
+
+## The Rule
+
+**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
+
+## Red Flags
+
+These thoughts mean STOP - you're rationalizing:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
+| "Let me gather information first" | Skills tell you HOW to gather information. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "This doesn't count as a task" | Action = task. Check for skills. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+
+## Skill Categories
+
+Locus provides skills across these categories:
+
+### Executive Suite (01-executive-suite/)
+Strategic leadership perspectives:
+- `locus:ceo-strategist` - Strategic vision and decision making
+- `locus:cto-architect` - Technical strategy and architecture
+- `locus:cpo-product` - Product vision and roadmap
+- `locus:cfo-analyst` - Financial analysis and planning
+- `locus:coo-operations` - Operations and execution
+
+### Product Management (02-product-management/)
+Product planning and execution:
+- `locus:product-manager` - Product planning and requirements
+- `locus:project-manager` - Project execution and tracking
+- `locus:scrum-master` - Agile process facilitation
+- `locus:program-manager` - Multi-project coordination
+- `locus:roadmap-strategist` - Long-term planning
+
+### Engineering Leadership (03-engineering-leadership/)
+Technical leadership and architecture:
+- `locus:tech-lead` - Technical leadership
+- `locus:staff-engineer` - Senior technical guidance
+- `locus:principal-engineer` - Architecture decisions
+- `locus:engineering-manager` - Team leadership
+- `locus:architect-reviewer` - Architecture review
+
+### Developer Specializations (04-developer-specializations/)
+Domain expertise in:
+- **Core**: frontend, backend, fullstack, mobile, api-designer
+- **Design**: ui-ux-designer
+- **Languages**: typescript, python, rust, golang, java
+- **Infrastructure**: devops, cloud, kubernetes, platform, security, sre, database-architect
+- **Data & AI**: data-engineer, data-scientist, ml-engineer, llm-architect
+- **Quality**: qa, performance, security-auditor, accessibility, test-automation-engineer
+
+### Specialists (05-specialists/)
+Specialized domain expertise:
+- `locus:compliance-specialist` - Regulatory compliance
+- `locus:technical-writer` - Documentation and technical writing
+
+## Skill Priority
+
+When multiple skills could apply, use this order:
+
+1. **Process skills first** (planning, debugging) - these determine HOW to approach the task
+2. **Role skills second** (product-manager, tech-lead) - these provide domain perspective
+3. **Implementation skills third** (frontend-developer, devops-engineer) - these guide execution
+
+## User Instructions
+
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.
+
+## Project Planning with Locus
+
+For project planning specifically, Locus guides you through 4 steps:
+
+```
+Step 1: Vision    -> What are we building and why?
+Step 2: Features  -> What will it do?
+Step 3: Design    -> How will it work?
+Step 4: Build     -> Let's make it
+```
+
+Use `/locus` to start a planning session, or say "I want to build..."
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/locus` | Start or resume a project |
+| `/locus-status` | Show current project progress |
+| `/locus-list` | List all projects |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `use_skill` | Load a specific skill |
+| `find_skills` | List all available skills |
+| `find_agents` | List all available agents |