flowmade-one/architecture
3
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add new commands, skills, and agents; remove token loading script

Browse Source 
- Add groom, plan-issues, and roadmap commands
- Add skills for backlog-grooming, forgejo, issue-writing, roadmap-planning
- Add agents directory structure
- Remove load-forgejo-token.sh and SessionStart hook (using fj auth instead)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2025-12-28 22:32:01 +01:00
committed by Hugo Nijhuis
parent fc5a400b94
commit 092538b097
10 changed files with 524 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
skills/backlog-grooming/SKILL.md Normal file
View File

@@ -0,0 +1,83 @@
# Backlog Grooming
How to review and improve existing issues.
## Grooming Checklist
For each issue, verify:
### 1. Title Clarity
- [ ] Starts with action verb
- [ ] Specific and descriptive
- [ ] Understandable without reading description
### 2. Description Quality
- [ ] Has clear summary
- [ ] Explains the "why"
- [ ] Provides enough context
### 3. Acceptance Criteria
- [ ] Criteria exist
- [ ] Each criterion is testable
- [ ] Criteria are specific (not vague)
- [ ] Complete set (nothing missing)
### 4. Scope
- [ ] Not too broad (can complete in reasonable time)
- [ ] Not too narrow (meaningful unit of work)
- [ ] Clear boundaries (what's included/excluded)
### 5. Dependencies
- [ ] Dependencies identified
- [ ] No circular dependencies
- [ ] Blocking issues are tracked
### 6. Labels
- [ ] Type label (bug/feature/etc)
- [ ] Priority if applicable
- [ ] Component labels if applicable
## Common Issues to Fix
### Vague Titles
- Bad: "Fix bug"
- Good: "Fix login form validation on empty email"
### Missing Acceptance Criteria
Add specific, testable criteria based on the description.
### Scope Creep
If issue covers multiple features, split into separate issues.
### Stale Issues
- Close if no longer relevant
- Update if context has changed
- Add "needs-triage" label if unclear
### Duplicate Issues
- Close duplicate with reference to original
- Merge relevant details into original
## Grooming Workflow
1. **Fetch open issues**: `fj issue search -s open`
2. **Review each issue** against checklist
3. **Improve or flag** issues that need work
4. **Update issue** with improvements: `fj issue edit <n> --body "..."`
5. **Add labels** as needed: `fj issue label add <n> <label>`
## Questions to Ask
When grooming, consider:
- "Could a developer start work on this today?"
- "How will we know when this is done?"
- "Is the scope clear?"
- "Are dependencies explicit?"
## Batch Grooming
When grooming multiple issues:
1. List all open issues
2. Categorize by quality (ready, needs-work, stale)
3. Focus on "needs-work" issues
4. Present summary of changes made

88
skills/forgejo/SKILL.md Normal file
View File

@@ -0,0 +1,88 @@
# Forgejo CLI (fj)
Command-line interface for interacting with Forgejo repositories.
## Authentication
The `fj` CLI authenticates via `fj auth login`. Credentials are stored locally by fj.
## Repository Detection
`fj` automatically detects the repository from git remotes when run inside a git repository.
## Common Commands
### Issues
```bash
# List issues
fj issue search -s open # Open issues
fj issue search -s closed # Closed issues
fj issue search # All issues
# View issue details
fj issue view <number> # Full issue details
# Create issue
fj issue create "<title>" --body "<body>"
# Edit issue
fj issue edit <number> --title "<new-title>"
fj issue edit <number> --body "<new-body>"
# Close/reopen
fj issue close <number>
fj issue reopen <number>
# Labels
fj issue label add <number> <label>
fj issue label remove <number> <label>
```
### Pull Requests
```bash
# List PRs
fj pr search -s open # Open PRs
fj pr search -s closed # Closed/merged PRs
# View PR
fj pr view <number> # PR details
fj pr view <number> diff # PR diff
# Create PR
fj pr create "<title>" --body "<body>"
fj pr create "<title>" --body "Closes #<issue>"
# PR status
fj pr status <number> # CI status, reviews
# Review
fj pr review <number> --approve
fj pr review <number> --request-changes --body "<feedback>"
fj pr review <number> --comment --body "<comment>"
# Merge
fj pr merge <number>
fj pr merge <number> --squash
```
### Repository
```bash
fj repo view # Repository info
fj repo clone <owner>/<repo> # Clone repository
```
## Output Formatting
Most commands support `--output` flag:
- `--output json` - Machine-readable JSON
- `--output table` - Tabular format (default for lists)
- `--output simple` - Plain text
## Tips
- Always verify you're in the correct repository before running commands
- Use `fj issue search` to find issue numbers before viewing/editing
- Reference issues in PR bodies with `Closes #N` for auto-linking

105
skills/issue-writing/SKILL.md Normal file
View File

@@ -0,0 +1,105 @@
# Issue Writing
How to write clear, actionable issues.
## Issue Structure
### Title
- Start with action verb: "Add", "Fix", "Update", "Remove", "Refactor"
- Be specific: "Add user authentication" not "Auth stuff"
- Keep under 60 characters when possible
### Description
```markdown
## Summary
One paragraph explaining what and why.
## Acceptance Criteria
- [ ] Specific, testable requirement
- [ ] Another requirement
- [ ] User can verify this works
## Context
Additional background, links, or references.
## Technical Notes (optional)
Implementation hints or constraints.
```
## Writing Acceptance Criteria
Good criteria are:
- **Specific**: "User sees error message" not "Handle errors"
- **Testable**: Can verify pass/fail
- **User-focused**: What the user experiences
- **Independent**: Each stands alone
Examples:
```markdown
- [ ] Login form validates email format before submission
- [ ] Invalid credentials show "Invalid email or password" message
- [ ] Successful login redirects to dashboard
- [ ] Session persists across browser refresh
```
## Issue Types
### Bug Report
```markdown
## Summary
Description of the bug.
## Steps to Reproduce
1. Go to...
2. Click...
3. Observe...
## Expected Behavior
What should happen.
## Actual Behavior
What happens instead.
## Environment
- Browser/OS/Version
```
### Feature Request
```markdown
## Summary
What feature and why it's valuable.
## Acceptance Criteria
- [ ] ...
## User Story (optional)
As a [role], I want [capability] so that [benefit].
```
### Technical Task
```markdown
## Summary
What technical work needs to be done.
## Scope
- Include: ...
- Exclude: ...
## Acceptance Criteria
- [ ] ...
```
## Labels
Use labels to categorize:
- `bug`, `feature`, `enhancement`, `refactor`
- `priority/high`, `priority/low`
- Component labels specific to project
## Dependencies
Reference related issues:
- "Depends on #N" - Must complete first
- "Blocks #N" - This blocks another
- "Related to #N" - Informational link

118
skills/roadmap-planning/SKILL.md Normal file
View File

@@ -0,0 +1,118 @@
# Roadmap Planning
How to plan features and create issues for implementation.
## Planning Process
### 1. Understand the Goal
- What capability or improvement is needed?
- Who benefits and how?
- What's the success criteria?
### 2. Break Down the Work
- Identify distinct components
- Define boundaries between pieces
- Aim for issues that are:
- Completable in 1-3 focused sessions
- Independently testable
- Clear in scope
### 3. Identify Dependencies
- Which pieces must come first?
- What can be parallelized?
- Are there external blockers?
### 4. Create Issues
- Follow issue-writing patterns
- Reference dependencies explicitly
- Use consistent labeling
## Breaking Down Features
### By Layer
```
Feature: User Authentication
├── Data layer: User model, password hashing
├── API layer: Login/logout endpoints
├── UI layer: Login form, session display
└── Integration: Connect all layers
```
### By User Story
```
Feature: Shopping Cart
├── Add item to cart
├── View cart contents
├── Update quantities
├── Remove items
└── Proceed to checkout
```
### By Technical Component
```
Feature: Real-time Updates
├── WebSocket server setup
├── Client connection handling
├── Message protocol
├── Reconnection logic
└── Integration tests
```
## Issue Ordering
### Dependency Chain
Create issues in implementation order:
1. Foundation (models, types, interfaces)
2. Core logic (business rules)
3. Integration (connecting pieces)
4. Polish (error handling, edge cases)
### Reference Pattern
In issue descriptions:
```markdown
## Dependencies
- Depends on #12 (user model)
- Depends on #13 (API setup)
```
## Creating Issues with fj
### Single Issue
```bash
fj issue create "Add user authentication endpoint" --body "$(cat <<'EOF'
## Summary
Create POST /api/auth/login endpoint for user authentication.
## Acceptance Criteria
- [ ] Endpoint accepts email and password
- [ ] Returns JWT token on success
- [ ] Returns 401 on invalid credentials
- [ ] Rate limits login attempts
## Dependencies
- Depends on #5 (user model)
EOF
)"
```
### Batch Creation
When creating multiple related issues:
1. Plan all issues first
2. Create in dependency order
3. Update earlier issues with forward references
## Roadmap View
To see current roadmap:
1. List open issues: `fj issue search -s open`
2. Group by labels/milestones
3. Identify blocked vs ready issues
4. Prioritize based on dependencies and value
## Planning Questions
Before creating issues, answer:
- "What's the minimum viable version?"
- "What can we defer?"
- "What are the riskiest parts?"
- "How will we validate each piece?"