init

.opencode/skills/project-organization/references/directory-patterns.md

@@ -0,0 +1,176 @@
+# Directory Patterns
+
+Detailed patterns for each top-level category. See SKILL.md Rule 1 for overview.
+
+## Documentation (`docs/`)
+
+Evergreen project documentation for humans and AI agents.
+
+```text
+docs/
+├── project-overview-pdr.md          # Product/project requirements
+├── system-architecture.md           # Architecture & components
+├── code-standards.md                # Coding conventions
+├── codebase-summary.md              # Auto-generated structure overview
+├── project-roadmap.md               # Milestones & progress
+├── project-changelog.md             # Version history
+├── design-guidelines.md             # UI/UX standards
+├── deployment-guide.md              # Deploy procedures
+├── journals/                        # Technical diary
+│   └── {YYMMDD-HHmm}-{slug}.md     # Session reflections, decisions
+└── decisions/                       # Architecture Decision Records
+    └── {YYMMDD}-{slug}.md           # ADR documents
+```
+
+**Rules:**
+- Evergreen docs: no date prefix, slug-only naming
+- Journals: always timestamped, one per session/event
+- ADRs: date-prefixed, sequential numbering optional
+- Keep docs under 200 lines; split into subsections if needed
+
+## Plans (`plans/`)
+
+Implementation plans, research, and agent communication.
+
+```text
+plans/
+├── {YYMMDD-HHmm}-{slug}/           # Timestamped plan folders
+│   ├── plan.md                      # Overview (<80 lines)
+│   ├── phase-{NN}-{name}.md         # Phase details
+│   ├── research/                    # Research for this plan
+│   │   └── researcher-{NN}-{topic}.md
+│   └── reports/                     # Agent reports scoped to plan
+│       ├── scout-report.md
+│       ├── code-reviewer-report.md
+│       └── tester-report.md
+├── reports/                         # Standalone agent reports
+│   └── {type}-{YYMMDD-HHmm}-{slug}.md
+├── research/                        # Standalone research
+│   └── researcher-{YYMMDD-HHmm}-{topic}.md
+├── templates/                       # Reusable plan templates
+│   └── {type}-template.md
+└── visuals/                         # Generated diagrams/previews
+    └── {slug}.{ext}
+```
+
+**Report type prefixes:** `scout-`, `researcher-`, `brainstorm-`, `code-reviewer-`, `tester-`, `debugger-`, `planner-`
+
+**Rules:**
+- Plan folders always timestamped
+- Phase files: `phase-{NN}-{name}.md` with zero-padded numbers (01, 02...)
+- Scoped reports go inside their plan folder
+- Standalone reports go in `plans/reports/`
+- plan.md: keep generic, under 80 lines, link to phase files
+
+## Tests (`tests/`)
+
+Test suites mirroring source structure.
+
+```text
+tests/
+├── unit/                            # Unit tests
+│   └── {module}.test.{ext}
+├── integration/                     # Integration tests
+│   └── {feature}.integration.{ext}
+├── e2e/                             # End-to-end tests
+│   └── {flow}.e2e.{ext}
+├── fixtures/                        # Test data/fixtures
+│   └── {name}.{ext}
+└── helpers/                         # Shared test utilities
+    └── {name}.{ext}
+```
+
+**Rules:**
+- Mirror source directory structure where practical
+- Use `.test.`, `.spec.`, `.integration.`, `.e2e.` suffixes
+- Fixtures: descriptive names, no dates
+- Follow project's existing test convention if one exists
+
+## Scripts (`scripts/`)
+
+Build, deploy, and utility scripts.
+
+```text
+scripts/
+├── {action}-{target}.{ext}          # e.g., prepare-release-assets.cjs
+├── {category}/                      # Group if 5+ scripts
+│   └── {action}-{target}.{ext}
+```
+
+**Rules:**
+- Kebab-case, verb-first naming: `generate-manifest.cjs`, `send-notification.py`
+- Group into subdirs only when 5+ scripts in same category
+- Include shebang line for shell scripts
+- No date prefixes (versioned in git)
+
+## Assets (`assets/`)
+
+Media, branding, designs, and generated content.
+
+```text
+assets/
+├── images/                          # Static images, screenshots
+│   └── {slug}.{ext}
+├── videos/                          # Video files
+│   ├── {slug}/                      # Multi-file: self-contained folder
+│   │   ├── master.mp4
+│   │   ├── scene-{NN}.mp4
+│   │   └── captions.srt
+│   └── {slug}.mp4                   # Single file: flat
+├── designs/                         # UI/UX designs, mockups
+│   └── {project}/
+│       ├── mockup-{variant}.{ext}
+│       └── exports/
+├── branding/                        # Logos, brand assets
+│   └── {name}-{variant}.{ext}       # logo-dark.svg, logo-icon.png
+├── generated/                       # AI-generated content
+│   └── {type}/                      # images/, audio/, text/
+│       └── {YYMMDD-HHmm}-{slug}.{ext}
+└── {custom-type}/                   # Project-specific categories
+    └── ...
+```
+
+**Rules:**
+- Single file → flat in category dir
+- Multi-file → self-contained subdirectory
+- Variants: append `-{variant}` suffix (not separate folders)
+- Size variants: `{name}-{width}x{height}.{ext}`
+- Platform variants: `{name}-{platform}.{ext}`
+- Generated content: always timestamped
+- Custom categories allowed for project-specific needs
+
+## Configuration (Root / `.config/`)
+
+```text
+project-root/
+├── .env                             # Environment variables (gitignored)
+├── .env.example                     # Env template (committed)
+├── .gitignore
+├── .eslintrc.*                      # Linter config
+├── tsconfig.json                    # TypeScript config
+├── package.json                     # Node.js manifest
+└── .config/                         # Optional: grouped configs
+    └── {tool}.{ext}
+```
+
+**Rules:**
+- Follow ecosystem conventions (package.json at root, not in .config/)
+- `.env` files: never commit actual secrets, only `.example` templates
+- Group into `.config/` only if ecosystem supports it
+
+## Guides (`guide/` or `guides/`)
+
+User-facing reference documentation, tutorials.
+
+```text
+guide/
+├── {topic}.md                       # Reference docs
+├── {topic}.yaml                     # Structured data
+└── {category}/                      # Group by category if 5+ files
+    └── {topic}.md
+```
+
+**Rules:**
+- Evergreen naming (no dates)
+- Flat structure unless 5+ files warrant categorization
+- Self-documenting names: `SKILLS.md`, `COMMANDS.md`, `ENVIRONMENT_RESOLVER.md`

.opencode/skills/project-organization/references/markdown-body-templates.md

@@ -0,0 +1,311 @@
+# Markdown Body Templates
+
+Standard content structures for each markdown document type. See SKILL.md Rule 4 for overview.
+
+## Universal Rules
+
+- Start with `# Title` (H1) — one per file
+- Frontmatter (`---`) for metadata when consumed by tools/automation
+- Sections ordered: context → content → next steps
+- Tables for structured data, lists for sequences
+- Sacrifice grammar for concision
+- List unresolved questions at end
+
+## Plan (plan.md)
+
+```markdown
+---
+title: "{Plan Title}"
+status: pending | in_progress | completed | cancelled
+created: YYYY-MM-DD
+---
+
+# {Plan Title}
+
+## Overview
+Brief description of what this plan accomplishes.
+
+## Phases
+
+| # | Phase | Status | File |
+|---|-------|--------|------|
+| 1 | {Phase name} | pending | [phase-01-{name}.md] |
+| 2 | {Phase name} | pending | [phase-02-{name}.md] |
+
+## Dependencies
+- {dependency 1}
+- {dependency 2}
+
+## Success Criteria
+- {criterion 1}
+- {criterion 2}
+```
+
+## Phase (phase-{NN}-{name}.md)
+
+```markdown
+# Phase {NN}: {Name}
+
+## Context Links
+- Plan: [plan.md](./plan.md)
+- Related: {links to reports, docs, code}
+
+## Overview
+- **Priority:** high | medium | low
+- **Status:** pending | in_progress | completed
+- **Description:** {brief description}
+
+## Key Insights
+- {finding from research}
+- {critical consideration}
+
+## Requirements
+### Functional
+- {requirement}
+### Non-functional
+- {requirement}
+
+## Architecture
+{system design, component interactions, data flow}
+
+## Related Code Files
+- **Modify:** {file paths}
+- **Create:** {file paths}
+- **Delete:** {file paths}
+
+## Implementation Steps
+1. {step with specific instructions}
+2. {step}
+
+## Todo
+- [ ] {task}
+- [ ] {task}
+
+## Success Criteria
+- {definition of done}
+
+## Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|-----------|
+| {risk} | {impact} | {mitigation} |
+
+## Next Steps
+- {dependency or follow-up}
+```
+
+## Report ({type}-report.md)
+
+```markdown
+---
+type: {scout | researcher | code-reviewer | tester | debugger | brainstorm}
+date: YYYY-MM-DD
+---
+
+# {Report Type}: {Subject}
+
+## Summary
+{2-3 sentence overview of findings}
+
+## Findings
+### {Finding 1}
+{details, evidence, code references}
+
+### {Finding 2}
+{details}
+
+## Recommendations
+1. {actionable recommendation}
+2. {recommendation}
+
+## Unresolved Questions
+- {question that needs further investigation}
+```
+
+## Journal (docs/journals/)
+
+```markdown
+---
+date: YYYY-MM-DD
+session: {session identifier or topic}
+---
+
+# Journal: {Date} — {Topic}
+
+## Context
+{what was being worked on, why}
+
+## What Happened
+- {key event/decision/discovery}
+- {event}
+
+## Reflection
+{honest assessment — what went well, what didn't, emotional state}
+
+## Decisions Made
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| {decision} | {why} | {what changes} |
+
+## Next Steps
+- {follow-up action}
+```
+
+## Doc (docs/*.md)
+
+```markdown
+# {Document Title}
+
+## Overview
+{brief description of what this document covers}
+
+## {Section 1}
+{content}
+
+## {Section 2}
+{content}
+
+## References
+- {link or reference}
+```
+
+No frontmatter needed for simple docs. Keep sections logical and scannable.
+
+## ADR (docs/decisions/)
+
+```markdown
+# ADR-{NNN}: {Decision Title}
+
+- **Status:** proposed | accepted | deprecated | superseded
+- **Date:** YYYY-MM-DD
+- **Deciders:** {who made this decision}
+
+## Context
+{what is the issue that motivates this decision}
+
+## Decision
+{what is the change being proposed/made}
+
+## Consequences
+### Positive
+- {benefit}
+### Negative
+- {trade-off}
+
+## Alternatives Considered
+### {Alternative 1}
+- **Pros:** {pros}
+- **Cons:** {cons}
+- **Why rejected:** {reason}
+```
+
+## Changelog
+
+```markdown
+# Changelog
+
+## [{version}] - YYYY-MM-DD
+
+### Added
+- {new feature}
+
+### Changed
+- {modification to existing feature}
+
+### Fixed
+- {bug fix}
+
+### Removed
+- {removed feature}
+
+### Deprecated
+- {feature marked for future removal}
+```
+
+Follow [Keep a Changelog](https://keepachangelog.com) format.
+
+## README
+
+```markdown
+# {Project Name}
+
+{one-line description}
+
+## Quick Start
+
+{minimal steps to get running}
+
+## Usage
+
+{how to use the project}
+
+## Development
+
+{setup for contributors}
+
+## Contributing
+
+{contribution guidelines}
+
+## License
+
+{license info}
+```
+
+## Guide
+
+```markdown
+# {Guide Title}
+
+## Prerequisites
+- {requirement}
+
+## Steps
+
+### Step 1: {Name}
+{instructions}
+
+### Step 2: {Name}
+{instructions}
+
+## Troubleshooting
+
+### {Common issue}
+**Problem:** {description}
+**Solution:** {fix}
+
+## FAQ
+
+### {Question}
+{Answer}
+```
+
+## Spec / Requirements
+
+```markdown
+# {Spec Title}
+
+## Overview
+{what this spec defines}
+
+## Requirements
+
+### Functional
+| ID | Requirement | Priority |
+|----|------------|----------|
+| F1 | {requirement} | must | should | could |
+
+### Non-functional
+| ID | Requirement | Metric |
+|----|------------|--------|
+| NF1 | {requirement} | {measurable target} |
+
+## Constraints
+- {constraint}
+
+## API / Interface
+{interface definitions, endpoints, schemas}
+
+## Acceptance Criteria
+- [ ] {criterion}
+- [ ] {criterion}
+```

.opencode/skills/project-organization/references/naming-conventions.md

@@ -0,0 +1,140 @@
+# Naming Conventions
+
+Comprehensive naming rules for all file types. See SKILL.md Rule 2 for overview.
+
+## Slug Generation
+
+### Rules
+
+- Convert title/topic to lowercase
+- Replace spaces and special chars with hyphens
+- Keep numbers
+- Max 50 characters (truncate at word boundary)
+- No leading/trailing hyphens
+- No consecutive hyphens
+
+### Examples
+
+| Title | Slug |
+|-------|------|
+| "User Authentication Flow" | `user-authentication-flow` |
+| "Fix: API Rate Limiting Bug #42" | `fix-api-rate-limiting-bug-42` |
+| "10 Tips for Better CI/CD" | `10-tips-for-better-ci-cd` |
+| "AI & Automation: A Guide" | `ai-automation-a-guide` |
+
+## Date Formats
+
+Use `$CK_PLAN_DATE_FORMAT` env var if set, otherwise default to `YYMMDD-HHmm`.
+
+| Format | Example | Use case |
+|--------|---------|----------|
+| `YYMMDD-HHmm` | `260304-1530` | Default for time-sensitive files |
+| `YYMMDD` | `260304` | Date-only (ADRs, daily reports) |
+| No date | `{slug}` | Evergreen content |
+
+### When to timestamp
+
+- Plans, reports, journals, sessions, brainstorms
+- Generated/AI content
+- Campaign-specific assets
+- Any content that becomes stale over time
+
+### When NOT to timestamp
+
+- Docs (architecture, standards, guides)
+- Config files
+- Source code
+- Templates
+- Brand assets (logos, styles)
+
+## Code File Naming
+
+Defer to `descriptive-name` hook for language-specific conventions:
+
+| Language | Convention | Example |
+|----------|-----------|---------|
+| JS/TS/Python/Shell | kebab-case | `user-auth-service.ts` |
+| C#/Java/Kotlin/Swift | PascalCase | `UserAuthService.cs` |
+| Go/Rust | snake_case | `user_auth_service.go` |
+| CSS/SCSS | kebab-case | `auth-form-styles.scss` |
+
+**Priority:** Self-documenting > short. A long descriptive name is better than a cryptic abbreviation.
+
+## File Extensions
+
+| Type | Extensions |
+|------|-----------|
+| Images | `.png`, `.jpg`, `.webp`, `.svg`, `.gif` |
+| Videos | `.mp4`, `.mov`, `.webm` |
+| Audio | `.mp3`, `.wav`, `.m4a` |
+| Documents | `.md`, `.txt`, `.pdf` |
+| Data | `.json`, `.yaml`, `.yml`, `.csv`, `.xml` |
+| Config | `.json`, `.yaml`, `.toml`, `.ini`, `.env` |
+
+## Variant Naming
+
+### Size variants
+
+Pattern: `{name}-{width}x{height}.{ext}`
+
+- `hero-1920x1080.png`
+- `thumbnail-300x200.jpg`
+- `banner-mobile-640x100.png`
+
+### Platform variants
+
+Pattern: `{name}-{platform}.{ext}`
+
+- `cover-youtube.png`
+- `post-instagram.png`
+- `ad-linkedin.jpg`
+
+### Theme/style variants
+
+Pattern: `{name}-{variant}.{ext}`
+
+- `logo-dark.svg`
+- `logo-light.svg`
+- `banner-alt.png`
+
+### Version variants
+
+Pattern: `{name}-v{N}.{ext}`
+
+- `mockup-v2.png`
+- `proposal-v3.pdf`
+
+## Directory Naming
+
+- Always kebab-case
+- Plural for collections: `tests/`, `scripts/`, `assets/`
+- Singular for specific items: `src/auth/`, `docs/`
+- No abbreviations: `configurations/` not `configs/` (exception: well-known like `docs/`, `src/`)
+
+## Report File Naming
+
+Pattern: `{agent-type}-{YYMMDD-HHmm}-{slug}.md`
+
+Examples:
+- `scout-260304-1530-auth-module-analysis.md`
+- `researcher-260304-1545-oauth2-comparison.md`
+- `brainstorm-260304-1600-caching-strategy.md`
+- `code-reviewer-260304-1700-api-endpoints.md`
+
+## Plan Folder Naming
+
+Pattern: `{YYMMDD-HHmm}-{slug}/`
+
+Examples:
+- `260304-1530-implement-user-authentication/`
+- `260305-0900-migrate-database-to-postgres/`
+- `260306-1400-redesign-dashboard-layout/`
+
+## Scene/Sequence Naming
+
+Pattern: `scene-{NN}-{position}.{ext}` or `step-{NN}-{name}.{ext}`
+
+- `scene-01-start.png`, `scene-01-end.png`
+- `step-01-install.md`, `step-02-configure.md`
+
+Zero-padded numbers for correct sorting.