@codeharbor/agent-playbook 0.1.0 → 0.1.1

package/skills/documentation-engineer/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: documentation-engineer
+description: Technical documentation expert for creating clear, comprehensive documentation. Use when user asks to write docs, create README, or document code.
+allowed-tools: Read, Write, Edit, Grep, Glob, WebFetch, WebSearch
+---
+
+# Documentation Engineer
+
+Expert in creating clear, comprehensive, and maintainable technical documentation.
+
+## When This Skill Activates
+
+Activates when you:
+- Ask to write documentation
+- Request README creation
+- Mention "docs" or "document this"
+- Need API documentation
+
+## Documentation Types
+
+### 1. README
+Every project should have a README with:
+
+```markdown
+# Project Name
+
+Brief description (what it does, why it exists)
+
+## Quick Start
+
+Installation and usage in 3 steps or less.
+
+## Installation
+
+Detailed installation instructions.
+
+## Usage
+
+Examples of common usage patterns.
+
+## Configuration
+
+Environment variables and configuration options.
+
+## Development
+
+How to run tests, build, and develop locally.
+
+## Contributing
+
+Guidelines for contributors.
+
+## License
+
+License information.
+```
+
+### 2. API Documentation
+
+For each endpoint/function:
+
+- **Description**: What it does
+- **Parameters**: Name, type, required/optional, description
+- **Return value**: Type and structure
+- **Errors**: Possible errors and conditions
+- **Examples**: Usage examples
+
+### 3. Code Comments
+
+Comment **why**, not **what**:
+
+```typescript
+// Bad: Sets the count to zero
+count = 0;
+
+// Good: Reset count for new measurement cycle
+count = 0;
+
+// Bad: Check if user is admin
+if (user.role === 'admin') {
+
+// Good: Only admins can bypass approval workflow
+if (user.role === 'admin') {
+```
+
+### 4. Architecture Documentation
+
+- System overview
+- Component relationships
+- Data flow
+- Design decisions
+- Trade-offs considered
+
+## Documentation Principles
+
+1. **Be Clear**: Use simple, direct language
+2. **Be Concise**: Respect the reader's time
+3. **Be Accurate**: Keep docs in sync with code
+4. **Be Complete**: Cover all public interfaces
+5. **Be Current**: Update docs when code changes
+
+## Writing Guidelines
+
+### Headings
+- Use sentence case for headings
+- Start with a verb or noun
+- Be descriptive
+
+### Code Examples
+- Show before/after when appropriate
+- Include import statements
+- Show expected output
+- Handle edge cases
+
+### Links
+- Use relative links for internal docs
+- Include anchors for sections
+- Test that links work
+
+### Diagrams
+- Use Mermaid for flowcharts and sequences
+- Keep diagrams simple
+- Add a title and legend
+
+## Documentation Checklist
+
+### README
+- [ ] Project description
+- [ ] Quick start guide
+- [ ] Installation instructions
+- [ ] Usage examples
+- [ ] Configuration guide
+- [ ] Contributing guidelines
+
+### Code Docs
+- [ ] All public functions documented
+- [ ] Parameters and returns documented
+- [ ] Examples provided for complex functions
+- [ ] Edge cases documented
+
+### API Docs
+- [ ] All endpoints documented
+- [ ] Request/response schemas
+- [ ] Authentication requirements
+- [ ] Error responses documented
+- [ ] Rate limits documented
+
+## Scripts
+
+Generate documentation structure:
+```bash
+python scripts/generate_docs.py
+```
+
+Validate documentation:
+```bash
+python scripts/validate_docs.py
+```
+
+## References
+
+- `references/readme-template.md` - README template
+- `references/api-template.md` - API documentation template
+- `references/style-guide.md` - Documentation style guide

package/skills/documentation-engineer/references/api-template.md

@@ -0,0 +1,22 @@
+# API Documentation Template
+
+## Endpoint: /resource
+
+**Method:** GET | POST | PUT | DELETE
+
+**Description:** What the endpoint does.
+
+### Parameters
+- `id` (string, required) - Resource identifier
+
+### Response
+```json
+{
+  "data": {}
+}
+```
+
+### Errors
+- `400` Bad Request
+- `401` Unauthorized
+- `404` Not Found

package/skills/documentation-engineer/references/readme-template.md

@@ -0,0 +1,25 @@
+# README Template
+
+## Overview
+Describe what the project does and why it exists.
+
+## Quick Start
+1. Install dependencies
+2. Configure environment
+3. Run the main command
+
+## Installation
+- Requirements
+- Setup steps
+
+## Usage
+Provide common usage examples.
+
+## Configuration
+List environment variables and configuration options.
+
+## Development
+How to lint, test, and build locally.
+
+## Contributing
+Explain how to propose changes.

package/skills/documentation-engineer/references/style-guide.md

@@ -0,0 +1,13 @@
+# Documentation Style Guide
+
+## Headings
+- Use sentence case
+- Keep headings short and specific
+
+## Code Blocks
+- Always specify a language
+- Keep examples minimal and runnable
+
+## Links
+- Use relative links for internal docs
+- Prefer stable URLs for external references

package/skills/documentation-engineer/scripts/generate_docs.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+# Template generator for documentation scaffold.
+
+from pathlib import Path
+import argparse
+import textwrap
+
+
+def write_output(path: Path, content: str, force: bool) -> bool:
+    if path.exists() and not force:
+        print(f"{path} already exists (use --force to overwrite)")
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return True
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate documentation scaffold.")
+    parser.add_argument("--output", default="docs/README.md", help="Output file path")
+    parser.add_argument("--name", default="example", help="Product or service name")
+    parser.add_argument("--owner", default="team", help="Owning team")
+    parser.add_argument("--force", action="store_true", help="Overwrite existing file")
+    args = parser.parse_args()
+
+    content = textwrap.dedent(
+        f"""\
+        # Documentation
+
+        ## Overview
+        Describe {args.name} and its purpose.
+
+        ## Ownership
+        - Owner: {args.owner}
+        - Support channel: TBD
+
+        ## Quickstart
+        1. Install dependencies
+        2. Configure environment
+        3. Run the service
+
+        ## Configuration
+        - Required environment variables
+        - Feature flags
+
+        ## Usage
+        Examples for {args.name}.
+
+        ## API Reference
+        - Endpoints or SDK methods
+
+        ## Troubleshooting
+        - Common errors and fixes
+
+        ## Changelog
+        - Recent updates
+        """
+    ).strip() + "\n"
+
+    output = Path(args.output)
+    if not write_output(output, content, args.force):
+        return 1
+    print(f"Wrote {output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/documentation-engineer/scripts/validate_docs.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+# Template validator for documentation scaffold.
+
+from pathlib import Path
+import argparse
+
+DEFAULT_REQUIRED = [
+    "## Overview",
+    "## Ownership",
+    "## Quickstart",
+    "## Configuration",
+    "## Usage",
+    "## Troubleshooting",
+]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate a generated artifact.")
+    parser.add_argument("--input", default="docs/README.md", help="Input file path")
+    parser.add_argument(
+        "--require",
+        action="append",
+        default=[],
+        help="Additional required section heading",
+    )
+    args = parser.parse_args()
+
+    path = Path(args.input)
+    if not path.exists():
+        print(f"Missing file: {path}")
+        return 1
+
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    text_lower = text.lower()
+    required = DEFAULT_REQUIRED + args.require
+    missing = [section for section in required if section.lower() not in text_lower]
+    if missing:
+        print("Missing required sections: " + ", ".join(missing))
+        return 1
+
+    print(f"Validated {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/figma-designer/README.md

@@ -0,0 +1,222 @@
+# Figma Designer Skill
+
+> "Transform Figma designs into implementation-ready specifications with pixel-perfect accuracy"
+
+## Overview
+
+This skill analyzes Figma designs through the Figma MCP server and generates detailed PRDs with precise visual specifications. It extracts design tokens, component specifications, and layout information that developers can implement directly.
+
+## Installation
+
+The skill should be symbolically linked to your Claude Code skills directory:
+
+```bash
+ln -s ~/agent-playbook/skills/figma-designer/SKILL.md ~/.claude/skills/figma-designer.md
+```
+
+## Prerequisites
+
+### Figma MCP Server
+
+Ensure the Figma MCP server is connected and accessible:
+
+```bash
+# Check if Figma MCP is available
+mcp-list
+```
+
+If not available, install from: https://github.com/modelcontextprotocol/servers
+
+Required Figma MCP tools:
+- `figma_get_file` - Get file metadata
+- `figma_get_nodes` - Get node details
+- `figma_get_components` - Get component information
+
+### Figma Access Token
+
+You need a Figma access token with appropriate permissions:
+
+```bash
+# Set environment variable
+export FIGMA_ACCESS_TOKEN="your_token_here"
+```
+
+## Usage
+
+### Basic Usage
+
+Provide a Figma link or ask to analyze a design:
+
+```
+You: Analyze this Figma design: https://www.figma.com/file/abc123/My-Design
+```
+
+The skill will automatically:
+1. Extract the file key from the URL
+2. Fetch design data via Figma MCP
+3. Analyze design tokens (colors, typography, spacing)
+4. Extract component hierarchy
+5. Generate visual specifications
+
+### With PRD Generation
+
+```
+You: Create a PRD from this Figma design: [URL]
+```
+
+Generates a complete 4-file PRD in `docs/`:
+- `{feature}-notes.md` - Design decisions
+- `{feature}-task-plan.md` - Implementation tasks
+- `{feature}-prd.md` - Product requirements
+- `{feature}-tech.md` - Technical specifications
+
+## What Gets Extracted
+
+### Design Tokens
+
+| Category | What's Extracted |
+|----------|-----------------|
+| **Colors** | Hex/RGBA values for primary, secondary, semantic colors |
+| **Typography** | Font families, sizes, weights, line heights, letter spacing |
+| **Spacing** | Padding, margin, gap values (typically 4/8/12/16px scale) |
+| **Borders** | Corner radius, border widths |
+| **Shadows** | Offset, blur, spread, color values |
+| **Icons** | Names, sizes, colors |
+| **Images** | URLs, dimensions, fit modes |
+
+### Component Analysis
+
+For each component found in the design:
+- Props (size, variant, state)
+- Layout (flex direction, alignment, gap, padding)
+- Styles (fill, stroke, effects)
+- Content (text, icons, images)
+- Constraints (responsive behavior)
+
+## Output Examples
+
+### Visual Specification
+
+```markdown
+## Screen: Login
+
+### Layout Structure
+```
+┌─────────────────────────────────────────┐
+│           Logo                          [Icon] │
+├─────────────────────────────────────────┤
+│  Welcome back                            │
+│  Sign in to continue                    │
+├─────────────────────────────────────────┤
+│  Email                    [✓]           │
+│  ┌────────────────────────────────┐    │
+│  └────────────────────────────────┘    │
+├─────────────────────────────────────────┤
+│  Password                [👁️]           │
+│  ┌────────────────────────────────┐    │
+│  └────────────────────────────────┘    │
+├─────────────────────────────────────────┤
+│         Forgot password?               │
+├─────────────────────────────────────────┤
+│  [      Sign In        ]               │
+└─────────────────────────────────────────┘
+```
+
+### Design Tokens
+
+```typescript
+// tokens.ts
+export const colors = {
+  primary: '#007AFF',
+  background: '#FFFFFF',
+  surface: '#F5F5F7',
+  textPrimary: '#1C1C1E',
+  textSecondary: '#8E8E93',
+};
+
+export const typography = {
+  displayLarge: {
+    fontSize: 28,
+    fontWeight: '700',
+    lineHeight: 34,
+  },
+  // ...
+};
+
+export const spacing = {
+  xs: 4,
+  sm: 8,
+  md: 12,
+  lg: 16,
+  xl: 24,
+  2xl: 32,
+};
+```
+
+## Integration with Other Skills
+
+### Typical Workflow
+
+```
+Figma URL → figma-designer → Visual Specs
+                                ↓
+                           prd-planner → PRD
+                                ↓
+                           implementation → Code
+                                ↓
+                           code-reviewer → Quality Check
+```
+
+### Auto-Triggers
+
+After figma-designer completes:
+- `prd-planner` (ask first) - Further refine PRD with 4-file pattern
+- `self-improving-agent` (background) - Learn design patterns
+- `session-logger` (auto) - Save design analysis session
+
+## Platform Support
+
+The skill generates specifications for:
+- **React Native** - Uses StyleSheet with exact pixel values
+- **React/Web** - CSS values with proper units
+- **SwiftUI** - Native SwiftUI values
+
+## Examples
+
+### Example 1: Quick Analysis
+
+```
+You: What are the colors used in this design?
+```
+
+Returns a table of all colors with their usage contexts.
+
+### Example 2: Component Spec
+
+```
+You: Extract the button component specifications
+```
+
+Returns props interface, variants, and all states.
+
+### Example 3: Full PRD
+
+```
+You: Create a complete PRD from this Figma file
+```
+
+Generates 4-file PRD with all visual specifications.
+
+## Tips
+
+1. **Organize Figma files** with clear naming conventions for better extraction
+2. **Use components** for reusable elements to get proper component specs
+3. **Set up auto-layout** in Figma for accurate layout information
+4. **Document prototypes** to include interaction states
+5. **Provide context** about target platform for platform-specific output
+
+## See Also
+
+- [SKILL.md](./SKILL.md) - Full skill definition with all templates
+- [prd-planner](../prd-planner/) - Create PRDs from design specs
+- [architecting-solutions](../architecting-solutions/) - Technical architecture