renolation/english
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
renolation
2026-04-12 01:06:31 +07:00
commit 10d660cbcb
1066 changed files with 228596 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
.opencode/skills/project-organization/SKILL.md Normal file
View File

@@ -0,0 +1,228 @@
---
name: ck:project-organization
description: Organize files, directories, and content structure in any project. Use when creating files, determining output paths, organizing existing assets, or standardizing project layout.
argument-hint: "[directories or files to organize]"
metadata:
author: claudekit
version: "2.0.0"
---
# Project Organization
Standardize file locations, naming conventions, directory structures, and markdown content templates for any project type.
## When to Use
- Creating any file that needs a consistent output path
- Organizing existing project files and directories
- Determining where to save plans, reports, docs, assets, tests
- Enforcing naming conventions across the project
- Structuring markdown content (plans, journals, reports, docs)
## Modes
| Mode | Trigger | Behavior |
|------|---------|----------|
| **Advisory** | Other skills/agents reference this skill | Return correct path + naming for requested file type |
| **Organize** | User invokes directly with dirs/files | Scan → propose changes → execute after confirm |
## Core Rules
### Rule 1 — Directory Categories
Every project file belongs to one of these top-level categories:
| Category | Path | Purpose |
|----------|------|---------|
| Source code | `src/` or project root | Application code (language-specific, not managed here) |
| Documentation | `docs/` | Human & AI readable docs, guides, specs |
| Plans | `plans/` | Implementation plans, research, agent reports |
| Tests | `tests/` or `test/` | Test suites (unit, integration, e2e) |
| Scripts | `scripts/` | Build, deploy, utility scripts |
| Assets | `assets/{type}/` | Media, branding, designs, generated content |
| Config | Root or `.config/` | dotfiles, config files, env files |
| Guides | `guide/` or `guides/` | User-facing reference docs, tutorials |
**Subcategories within each:**
```
docs/
├── journals/ # Technical diary, session reflections
├── decisions/ # ADRs (Architecture Decision Records)
└── *.md # Evergreen docs (architecture, standards, roadmap)
plans/
├── {date-slug}/ # Timestamped plan folders
│ ├── plan.md # Overview
│ ├── phase-{NN}-{name}.md # Phase details
│ ├── research/ # Research materials for this plan
│ └── reports/ # Agent reports scoped to this plan
├── reports/ # Standalone agent reports (not plan-scoped)
├── templates/ # Reusable plan templates
└── visuals/ # Generated diagrams, previews
assets/
├── images/ # Static images, screenshots
├── videos/ # Video files
├── designs/ # UI/UX designs, mockups
├── branding/ # Logos, brand assets
├── generated/ # AI-generated content
└── {custom-type}/ # Project-specific asset categories
```
### Rule 2 — Naming Patterns
All filenames use **kebab-case**, self-documenting names.
**Three naming modes based on content temporality:**
| Mode | Pattern | When to use | Examples |
|------|---------|-------------|---------|
| **Timestamped** | `{YYMMDD-HHmm}-{slug}` | Time-sensitive: plans, reports, journals, sessions | `260304-1530-auth-plan` |
| **Evergreen** | `{slug}` | Stable docs, configs, guides | `system-architecture.md` |
| **Variant** | `{slug}-{variant}.{ext}` | Multiple versions of same asset | `logo-dark.svg`, `hero-1920x1080.png` |
**Slug rules:**
- Lowercase, hyphens only (no underscores, spaces, special chars)
- Max 50 chars (truncate at word boundary)
- Self-documenting: readable without opening the file
- No leading/trailing hyphens
**Date format:** Use `$CK_PLAN_DATE_FORMAT` env var or default `YYMMDD-HHmm`.
```bash
date +%y%m%d-%H%M # Bash
```
**Code file naming:** Defer to `descriptive-name` hook — kebab-case for JS/TS/Python/Shell, PascalCase for C#/Java/Swift, snake_case for Go/Rust.
### Rule 3 — Nesting Logic
Decide between flat file vs folder based on output count:
| Scenario | Pattern | Example |
|----------|---------|---------|
| Single file output | Flat file in category dir | `docs/journals/260304-session-review.md` |
| Multi-file output | Self-contained subdirectory | `plans/260304-auth-impl/plan.md` + `phase-01-*.md` |
| Scoped to parent | Nested under parent context | `plans/260304-auth-impl/reports/scout-report.md` |
| Platform-specific | Platform subdirectory | `assets/posts/twitter/`, `assets/posts/linkedin/` |
| Variant-based | Flat with variant suffix | `assets/branding/logo-light.svg`, `logo-dark.svg` |
**Empty directories:** Add `.gitkeep` to preserve in git.
### Rule 4 — Markdown Body Standards
Every markdown file MUST have consistent structure based on its type.
**Universal rules for all markdown:**
- Start with a `# Title` (H1)
- Use frontmatter (`---`) for metadata when the file is consumed by tools
- Keep sections ordered: context → content → next steps
- Use tables for structured data, lists for sequences
- Sacrifice grammar for concision
**Quick reference — required sections by type:**
| Type | Key sections |
|------|-------------|
| **Plan** | frontmatter → overview → phases with status → dependencies → success criteria |
| **Phase** | context links → overview → requirements → architecture → impl steps → todo checklist → risks |
| **Report** | frontmatter → summary → findings → recommendations → unresolved questions |
| **Journal** | frontmatter → context → what happened → reflection → decisions → next |
| **Doc** | title → overview → content sections → references |
| **ADR** | status → context → decision → consequences → alternatives considered |
| **Changelog** | version blocks → categories (added/changed/fixed/removed/deprecated) |
| **README** | name → badges → description → quick start → usage → contributing → license |
| **Guide** | title → prerequisites → step-by-step → troubleshooting → FAQ |
| **Spec** | overview → requirements → constraints → API/interface → acceptance criteria |
Load: `references/markdown-body-templates.md` for full templates.
### Rule 5 — Path Resolution Decision Tree
When creating a new file, follow this decision tree:
```
1. Is it source code?
→ YES: src/ or project root (follow language conventions)
→ NO: continue
2. Is it a test?
→ YES: tests/ (mirror source structure)
→ NO: continue
3. Is it an implementation plan or agent output?
→ Plan: plans/{date-slug}/
→ Agent report (plan-scoped): plans/{date-slug}/reports/
→ Agent report (standalone): plans/reports/
→ Research: plans/{date-slug}/research/ or plans/research/
→ NO: continue
4. Is it documentation for humans/AI?
→ Technical journal: docs/journals/{date-slug}.md
→ Architecture decision: docs/decisions/{date-slug}.md
→ Evergreen doc: docs/{slug}.md
→ NO: continue
5. Is it a media/design/brand asset?
→ assets/{type}/{naming-per-rule-2}
→ NO: continue
6. Is it a utility script?
→ scripts/{slug}.{ext}
→ NO: continue
7. Is it configuration?
→ Root or .config/ (follow ecosystem conventions)
```
## Organize Mode Actions
When invoked directly with `/ck:project-organization [targets]`:
1. **Scan** — List all files in target dirs, categorize by type
2. **Analyze** — Check naming violations, misplaced files, inconsistencies
3. **Propose** — Present a migration plan (from → to) as a table
4. **Confirm** — Ask user approval before any moves
5. **Execute** — Move/rename files, create missing directories
6. **Verify** — List final structure, flag any remaining issues
**Safety:**
- Never overwrite existing files (prompt on conflict)
- Never touch `.git/`, `node_modules/`, `.env` files
- Create backups when renaming (git handles this)
- Respect `.gitignore` patterns
## File Type Reference
Load: `references/directory-patterns.md` for detailed patterns per category.
Load: `references/naming-conventions.md` for slug generation, date formats, variant naming.
## Integration
This skill is the **single source of truth** for file organization.
Other skills reference it when determining output paths:
- `plan` / `brainstorm` → plans/ structure
- `journal` → docs/journals/
- `cook` / `fix` → source code paths (defer to language conventions)
- `test` → tests/ structure
- `docs` / `docs-manager` → docs/ structure
- `scout` / `research` → plans/reports/ or plans/{plan}/research/
- `code-review` → plans/reports/
- `project-management` → docs/ + plans/
- `ui-ux-designer` / `frontend-design` → assets/designs/
- `ai-artist` / `ai-multimodal` → assets/generated/
- `media-processing` → assets/videos/, assets/images/
- `git` → respects all naming conventions
- `descriptive-name` hook → code file naming (JS/TS/Python/Shell = kebab-case)
## Pre-Output Checklist
Before writing any file:
1. Determine category → get base path (Rule 1)
2. Choose naming mode → timestamped/evergreen/variant (Rule 2)
3. Decide nesting → flat or subdirectory (Rule 3)
4. Apply body template if markdown (Rule 4)
5. Check if file/folder exists (avoid overwrite)
6. Create directory structure if needed

176
.opencode/skills/project-organization/references/directory-patterns.md Normal file
View File

@@ -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`

311
.opencode/skills/project-organization/references/markdown-body-templates.md Normal file
View File

@@ -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}
```

140
.opencode/skills/project-organization/references/naming-conventions.md Normal file
View File

@@ -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.