@codeharbor/agent-playbook 0.1.0 → 0.1.2

package/skills/deployment-engineer/scripts/generate_deploy.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+# Template generator for deployment plan.
+
+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 a deployment plan.")
+    parser.add_argument("--output", default="deploy-plan.md", help="Output file path")
+    parser.add_argument("--name", default="example", help="Service or app name")
+    parser.add_argument("--env", default="production", help="Target environment")
+    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"""\
+        # Deployment Plan
+
+        ## Overview
+        - Service: {args.name}
+        - Environment: {args.env}
+        - Owner: {args.owner}
+
+        ## Preconditions
+        - Release approved
+        - Change window confirmed
+        - Backups verified
+
+        ## Steps
+        1. Build and publish artifacts
+        2. Deploy to staging and run smoke tests
+        3. Run migrations (if needed)
+        4. Deploy to {args.env}
+        5. Verify health checks and dashboards
+
+        ## Verification
+        - Health endpoint returns 200
+        - Key metrics within baseline
+        - Error budget stable
+
+        ## Rollback
+        - Revert to last known good release
+        - Disable feature flags
+        - Communicate rollback status
+
+        ## Observability
+        - Dashboard links
+        - Alert channels
+        """
+    ).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/deployment-engineer/scripts/validate_deploy.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+# Template validator for deployment plan.
+
+from pathlib import Path
+import argparse
+
+DEFAULT_REQUIRED = [
+    "## Overview",
+    "## Preconditions",
+    "## Steps",
+    "## Verification",
+    "## Rollback",
+    "## Observability",
+]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate a generated artifact.")
+    parser.add_argument("--input", default="deploy-plan.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/documentation-engineer/README.md

@@ -0,0 +1,41 @@
+# Documentation Engineer
+
+> A Claude Code skill for creating clear, comprehensive documentation.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Write documentation for this API
+You: Create a README
+You: Document this code
+```
+
+## Documentation Types
+
+| Type | Description |
+|------|-------------|
+| **README** | Project overview and quick start |
+| **API Docs** | Endpoint/function documentation |
+| **Code Comments** | Inline explanations |
+| **Architecture** | System design documentation |
+
+## Scripts
+
+Generate documentation structure:
+```bash
+python scripts/generate_docs.py
+```
+
+Validate documentation:
+```bash
+python scripts/validate_docs.py
+```
+
+## Resources
+
+- [Google Developer Documentation Style Guide](https://developers.google.com/tech-writing/one)
+- [Diátaxis Framework](https://diataxis.fr/)

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())