feat(code): add skills from core-claude
Migrated 5 skills from host-uk/core-claude: - core: CLI command reference - go: Go framework patterns - php: PHP module patterns - go-agent: Autonomous Go development agent - php-agent: Autonomous PHP development agent Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
b504cc31ca
commit
9c3ff81787
5 changed files with 1041 additions and 0 deletions
60
claude/code/skills/core/SKILL.md
Normal file
60
claude/code/skills/core/SKILL.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
---
|
||||
name: core
|
||||
description: Use when working in host-uk repositories, running tests, building, releasing, or managing multi-repo workflows. Provides the core CLI command reference.
|
||||
---
|
||||
|
||||
# Core CLI
|
||||
|
||||
The `core` command provides a unified interface for Go/PHP development and multi-repo management.
|
||||
|
||||
**Rule:** Always prefer `core <command>` over raw commands.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| Go tests | `core go test` |
|
||||
| Go coverage | `core go cov` |
|
||||
| Go format | `core go fmt --fix` |
|
||||
| Go lint | `core go lint` |
|
||||
| PHP dev server | `core php dev` |
|
||||
| PHP tests | `core php test` |
|
||||
| PHP format | `core php fmt --fix` |
|
||||
| Build | `core build` |
|
||||
| Preview release | `core ci` |
|
||||
| Publish | `core ci --were-go-for-launch` |
|
||||
| Multi-repo status | `core dev health` |
|
||||
| Commit dirty repos | `core dev commit` |
|
||||
| Push repos | `core dev push` |
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
Go project?
|
||||
tests: core go test
|
||||
format: core go fmt --fix
|
||||
build: core build
|
||||
|
||||
PHP project?
|
||||
dev: core php dev
|
||||
tests: core php test
|
||||
format: core php fmt --fix
|
||||
deploy: core php deploy
|
||||
|
||||
Multiple repos?
|
||||
status: core dev health
|
||||
commit: core dev commit
|
||||
push: core dev push
|
||||
```
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
| Wrong | Right |
|
||||
|-------|-------|
|
||||
| `go test ./...` | `core go test` |
|
||||
| `go build` | `core build` |
|
||||
| `php artisan serve` | `core php dev` |
|
||||
| `./vendor/bin/pest` | `core php test` |
|
||||
| `git status` per repo | `core dev health` |
|
||||
|
||||
Run `core --help` or `core <cmd> --help` for full options.
|
||||
420
claude/code/skills/go-agent/SKILL.md
Normal file
420
claude/code/skills/go-agent/SKILL.md
Normal file
|
|
@ -0,0 +1,420 @@
|
|||
---
|
||||
name: go-agent
|
||||
description: Autonomous Go development agent - picks up issues, implements, handles reviews, merges
|
||||
---
|
||||
|
||||
# Go Agent Skill
|
||||
|
||||
You are an autonomous Go development agent working on the Host UK Go projects (primarily the `core` CLI). You continuously pick up issues, implement solutions, handle code reviews, and merge PRs.
|
||||
|
||||
## Workflow Loop
|
||||
|
||||
This skill runs as a continuous loop:
|
||||
|
||||
```
|
||||
1. CHECK PENDING PRs → Fix reviews if CodeRabbit commented
|
||||
2. FIND ISSUE → Pick a Go issue from host-uk org
|
||||
3. IMPLEMENT → Create branch, code, test, push
|
||||
4. HANDLE REVIEW → Wait for/fix CodeRabbit feedback
|
||||
5. MERGE → Merge when approved
|
||||
6. REPEAT → Start next task
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
Track your work with these variables:
|
||||
- `PENDING_PRS`: PRs waiting for CodeRabbit review
|
||||
- `CURRENT_ISSUE`: Issue currently being worked on
|
||||
- `CURRENT_BRANCH`: Branch for current work
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Check Pending PRs
|
||||
|
||||
Before starting new work, check if any of your pending PRs have CodeRabbit reviews ready.
|
||||
|
||||
```bash
|
||||
# List your open PRs in the core repo
|
||||
gh pr list --repo host-uk/core --author=@me --state=open --json number,title,headRefName,url
|
||||
|
||||
# For each PR, check CodeRabbit status
|
||||
gh api repos/host-uk/core/commits/{sha}/status --jq '.statuses[] | select(.context | contains("coderabbit")) | {context, state, description}'
|
||||
```
|
||||
|
||||
### If CodeRabbit review is complete:
|
||||
- **Success (no issues)**: Merge the PR
|
||||
- **Has comments**: Fix the issues, commit, push, continue to next task
|
||||
|
||||
```bash
|
||||
# Check for new reviews
|
||||
gh api repos/host-uk/core/pulls/{pr_number}/reviews --jq 'sort_by(.submitted_at) | .[-1] | {author: .user.login, state: .state, body: .body[:500]}'
|
||||
|
||||
# If actionable comments, read and fix them
|
||||
# Then commit and push:
|
||||
git add -A && git commit -m "fix: address CodeRabbit feedback
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
git push
|
||||
```
|
||||
|
||||
### Merging PRs
|
||||
```bash
|
||||
# When CodeRabbit approves (status: success), merge without admin
|
||||
gh pr merge {pr_number} --squash --repo host-uk/core
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Find an Issue
|
||||
|
||||
Search for Go issues in the Host UK organization.
|
||||
|
||||
```bash
|
||||
# Find open issues labeled for Go
|
||||
gh search issues --owner=host-uk --state=open --label="lang:go" --json number,title,repository,url --limit=10
|
||||
|
||||
# Or list issues in the core repo directly
|
||||
gh issue list --repo host-uk/core --state=open --json number,title,labels,body --limit=20
|
||||
|
||||
# Check for agent-ready issues
|
||||
gh issue list --repo host-uk/core --state=open --label="agent:ready" --json number,title,body
|
||||
```
|
||||
|
||||
### Issue Selection Criteria
|
||||
1. **Priority**: Issues with `priority:high` or `good-first-issue` labels
|
||||
2. **Dependencies**: Check if issue depends on other incomplete work
|
||||
3. **Scope**: Prefer issues that can be completed in one session
|
||||
4. **Labels**: Look for `agent:ready`, `help-wanted`, or `enhancement`
|
||||
|
||||
### Claim the Issue
|
||||
```bash
|
||||
# Comment to claim the issue
|
||||
gh issue comment {number} --repo host-uk/core --body "I'm picking this up. Starting work now."
|
||||
|
||||
# Assign yourself (if you have permission)
|
||||
gh issue edit {number} --repo host-uk/core --add-assignee @me
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Implement the Solution
|
||||
|
||||
### Setup Branch
|
||||
```bash
|
||||
# Navigate to the core package
|
||||
cd packages/core
|
||||
|
||||
# Ensure you're on dev and up to date
|
||||
git checkout dev && git pull
|
||||
|
||||
# Create feature branch
|
||||
git checkout -b feature/issue-{number}-{short-description}
|
||||
```
|
||||
|
||||
### Development Workflow
|
||||
1. **Read the code** - Understand the package structure
|
||||
2. **Write tests first** - TDD approach when possible
|
||||
3. **Implement the solution** - Follow Go best practices
|
||||
4. **Run tests** - Ensure all tests pass
|
||||
|
||||
```bash
|
||||
# Run tests (using Task)
|
||||
task test
|
||||
|
||||
# Or directly with go
|
||||
go test ./...
|
||||
|
||||
# Run tests with coverage
|
||||
task cov
|
||||
|
||||
# Run linting
|
||||
task lint
|
||||
|
||||
# Or with golangci-lint directly
|
||||
golangci-lint run
|
||||
|
||||
# Build to check compilation
|
||||
go build ./...
|
||||
```
|
||||
|
||||
### Go Code Quality Checklist
|
||||
- [ ] Tests written and passing
|
||||
- [ ] Code follows Go conventions (gofmt, effective go)
|
||||
- [ ] Error handling is proper (no ignored errors)
|
||||
- [ ] No unused imports or variables
|
||||
- [ ] Documentation for exported functions
|
||||
- [ ] Context passed where appropriate
|
||||
- [ ] Interfaces used for testability
|
||||
|
||||
### Go-Specific Patterns
|
||||
|
||||
**Error Handling:**
|
||||
```go
|
||||
// Use errors.E for contextual errors
|
||||
return errors.E("service.method", "what failed", err)
|
||||
|
||||
// Or errors.Wrap for wrapping
|
||||
return errors.Wrap(err, "service.method", "description")
|
||||
```
|
||||
|
||||
**Test Naming Convention:**
|
||||
```go
|
||||
// Use _Good, _Bad, _Ugly suffix pattern
|
||||
func TestMyFunction_Good_ValidInput(t *testing.T) { ... }
|
||||
func TestMyFunction_Bad_InvalidInput(t *testing.T) { ... }
|
||||
func TestMyFunction_Ugly_PanicCase(t *testing.T) { ... }
|
||||
```
|
||||
|
||||
**i18n Strings:**
|
||||
```go
|
||||
// Use i18n package for user-facing strings
|
||||
i18n.T("cmd.mycommand.description")
|
||||
i18n.Label("status")
|
||||
```
|
||||
|
||||
### Creating Sub-Issues
|
||||
If the issue reveals additional work needed:
|
||||
|
||||
```bash
|
||||
# Create a follow-up issue
|
||||
gh issue create --repo host-uk/core \
|
||||
--title "Follow-up: {description}" \
|
||||
--body "Discovered while working on #{original_issue}
|
||||
|
||||
## Context
|
||||
{explain what was found}
|
||||
|
||||
## Proposed Solution
|
||||
{describe the approach}
|
||||
|
||||
## References
|
||||
- Parent issue: #{original_issue}" \
|
||||
--label "lang:go,follow-up"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Push and Create PR
|
||||
|
||||
```bash
|
||||
# Stage and commit
|
||||
git add -A
|
||||
git commit -m "feat({pkg}): {description}
|
||||
|
||||
{longer description if needed}
|
||||
|
||||
Closes #{issue_number}
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
|
||||
# Push
|
||||
git push -u origin feature/issue-{number}-{short-description}
|
||||
|
||||
# Create PR
|
||||
gh pr create --repo host-uk/core \
|
||||
--title "feat({pkg}): {description}" \
|
||||
--body "$(cat <<'EOF'
|
||||
## Summary
|
||||
{Brief description of changes}
|
||||
|
||||
## Changes
|
||||
- {Change 1}
|
||||
- {Change 2}
|
||||
|
||||
## Test Plan
|
||||
- [ ] Unit tests added/updated
|
||||
- [ ] `task test` passes
|
||||
- [ ] `task lint` passes
|
||||
- [ ] Manual testing completed
|
||||
|
||||
Closes #{issue_number}
|
||||
|
||||
---
|
||||
Generated with Claude Code
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Handle CodeRabbit Review
|
||||
|
||||
After pushing, CodeRabbit will automatically review. Track PR status:
|
||||
|
||||
```bash
|
||||
# Check CodeRabbit status on latest commit
|
||||
gh api repos/host-uk/core/commits/$(git rev-parse HEAD)/status --jq '.statuses[] | select(.context | contains("coderabbit"))'
|
||||
```
|
||||
|
||||
### While Waiting
|
||||
Instead of blocking, **start working on the next issue** (go to Step 2).
|
||||
|
||||
### When Review Arrives
|
||||
```bash
|
||||
# Check the review
|
||||
gh api repos/host-uk/core/pulls/{pr_number}/reviews --jq '.[-1]'
|
||||
|
||||
# If "Actionable comments posted: N", fix them:
|
||||
# 1. Read each comment
|
||||
# 2. Make the fix
|
||||
# 3. Commit with clear message
|
||||
# 4. Push
|
||||
```
|
||||
|
||||
### Common CodeRabbit Feedback for Go
|
||||
- **Unused variables**: Remove or use them (Go compiler usually catches this)
|
||||
- **Error not checked**: Handle or explicitly ignore with `_ =`
|
||||
- **Missing context**: Add `ctx context.Context` parameter
|
||||
- **Race conditions**: Use mutex or channels
|
||||
- **Resource leaks**: Add `defer` for cleanup
|
||||
- **Inefficient code**: Use `strings.Builder`, avoid allocations in loops
|
||||
- **Missing documentation**: Add doc comments for exported symbols
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Merge and Close
|
||||
|
||||
When CodeRabbit status shows "Review completed" with state "success":
|
||||
|
||||
```bash
|
||||
# Merge the PR (squash merge)
|
||||
gh pr merge {pr_number} --squash --repo host-uk/core
|
||||
|
||||
# The issue will auto-close if "Closes #N" was in PR body
|
||||
# Otherwise, close manually:
|
||||
gh issue close {number} --repo host-uk/core
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Restart Loop
|
||||
|
||||
After merging:
|
||||
|
||||
1. Remove PR from `PENDING_PRS`
|
||||
2. Check remaining pending PRs for reviews
|
||||
3. Pick up next issue
|
||||
4. **Restart this skill** to continue the loop
|
||||
|
||||
```
|
||||
>>> LOOP COMPLETE - Restart /go-agent to continue working <<<
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Go Packages Reference (core CLI)
|
||||
|
||||
| Package | Purpose |
|
||||
|---------|---------|
|
||||
| `pkg/cli` | Command framework, styles, output |
|
||||
| `pkg/errors` | Error handling with context |
|
||||
| `pkg/i18n` | Internationalization |
|
||||
| `pkg/qa` | QA commands (watch, review) |
|
||||
| `pkg/setup` | Setup commands (github, bootstrap) |
|
||||
| `pkg/dev` | Multi-repo dev workflow |
|
||||
| `pkg/go` | Go tooling commands |
|
||||
| `pkg/php` | PHP tooling commands |
|
||||
| `pkg/build` | Build system |
|
||||
| `pkg/release` | Release management |
|
||||
| `pkg/sdk` | SDK generators |
|
||||
| `pkg/container` | Container/VM management |
|
||||
| `pkg/agentic` | Agent orchestration |
|
||||
| `pkg/framework/core` | Core DI framework |
|
||||
|
||||
---
|
||||
|
||||
## Task Commands Reference
|
||||
|
||||
```bash
|
||||
# Testing
|
||||
task test # Run all tests
|
||||
task test:verbose # Verbose output
|
||||
task test:run -- Name # Run specific test
|
||||
task cov # Coverage report
|
||||
|
||||
# Code Quality
|
||||
task fmt # Format code
|
||||
task lint # Run linter
|
||||
task qa # Full QA (fmt, vet, lint, test)
|
||||
task qa:quick # Quick QA (no tests)
|
||||
|
||||
# Building
|
||||
task cli:build # Build CLI to ./bin/core
|
||||
task cli:install # Install to system
|
||||
|
||||
# Other
|
||||
task mod:tidy # go mod tidy
|
||||
task review # CodeRabbit review
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### CodeRabbit Not Reviewing
|
||||
```bash
|
||||
# Check commit status
|
||||
gh api repos/host-uk/core/commits/$(git rev-parse HEAD)/status
|
||||
|
||||
# Check if webhooks are configured
|
||||
gh api repos/host-uk/core/hooks
|
||||
```
|
||||
|
||||
### Tests Failing
|
||||
```bash
|
||||
# Run with verbose output
|
||||
go test -v ./...
|
||||
|
||||
# Run specific test
|
||||
go test -run TestName ./pkg/...
|
||||
|
||||
# Run with race detector
|
||||
go test -race ./...
|
||||
```
|
||||
|
||||
### Build Errors
|
||||
```bash
|
||||
# Check for missing dependencies
|
||||
go mod tidy
|
||||
|
||||
# Verify build
|
||||
go build ./...
|
||||
|
||||
# Check for vet issues
|
||||
go vet ./...
|
||||
```
|
||||
|
||||
### Merge Conflicts
|
||||
```bash
|
||||
# Rebase on dev
|
||||
git fetch origin dev
|
||||
git rebase origin/dev
|
||||
|
||||
# Resolve conflicts, then continue
|
||||
git add .
|
||||
git rebase --continue
|
||||
git push --force-with-lease
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **One issue per PR** - Keep changes focused
|
||||
2. **Small commits** - Easier to review and revert
|
||||
3. **Descriptive messages** - Help future maintainers
|
||||
4. **Test coverage** - Don't decrease coverage
|
||||
5. **Documentation** - Update if behavior changes
|
||||
6. **Error context** - Use errors.E with service.method prefix
|
||||
7. **i18n strings** - Add to en_GB.json for user-facing text
|
||||
|
||||
## Labels Reference
|
||||
|
||||
- `lang:go` - Go code changes
|
||||
- `agent:ready` - Ready for AI agent pickup
|
||||
- `good-first-issue` - Simple, well-defined tasks
|
||||
- `priority:high` - Should be addressed soon
|
||||
- `follow-up` - Created from another issue
|
||||
- `needs:review` - Awaiting human review
|
||||
- `bug` - Something isn't working
|
||||
- `enhancement` - New feature or improvement
|
||||
107
claude/code/skills/go/SKILL.md
Normal file
107
claude/code/skills/go/SKILL.md
Normal file
|
|
@ -0,0 +1,107 @@
|
|||
---
|
||||
name: core-go
|
||||
description: Use when creating Go packages or extending the core CLI.
|
||||
---
|
||||
|
||||
# Go Framework Patterns
|
||||
|
||||
Core CLI uses `pkg/` for reusable packages. Use `core go` commands.
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
core/
|
||||
├── main.go # CLI entry point
|
||||
├── pkg/
|
||||
│ ├── cli/ # CLI framework, output, errors
|
||||
│ ├── {domain}/ # Domain package
|
||||
│ │ ├── cmd_{name}.go # Cobra command definitions
|
||||
│ │ ├── service.go # Business logic
|
||||
│ │ └── *_test.go # Tests
|
||||
│ └── ...
|
||||
└── internal/ # Private packages
|
||||
```
|
||||
|
||||
## Adding a CLI Command
|
||||
|
||||
1. Create `pkg/{domain}/cmd_{name}.go`:
|
||||
|
||||
```go
|
||||
package domain
|
||||
|
||||
import (
|
||||
"github.com/host-uk/core/pkg/cli"
|
||||
"github.com/spf13/cobra"
|
||||
)
|
||||
|
||||
func NewNameCmd() *cobra.Command {
|
||||
cmd := &cobra.Command{
|
||||
Use: "name",
|
||||
Short: cli.T("domain.name.short"),
|
||||
RunE: func(cmd *cobra.Command, args []string) error {
|
||||
// Implementation
|
||||
cli.Success("Done")
|
||||
return nil
|
||||
},
|
||||
}
|
||||
return cmd
|
||||
}
|
||||
```
|
||||
|
||||
2. Register in parent command.
|
||||
|
||||
## CLI Output Helpers
|
||||
|
||||
```go
|
||||
import "github.com/host-uk/core/pkg/cli"
|
||||
|
||||
cli.Success("Operation completed") // Green check
|
||||
cli.Warning("Something to note") // Yellow warning
|
||||
cli.Error("Something failed") // Red error
|
||||
cli.Info("Informational message") // Blue info
|
||||
cli.Fatal(err) // Print error and exit 1
|
||||
|
||||
// Structured output
|
||||
cli.Table(headers, rows)
|
||||
cli.JSON(data)
|
||||
```
|
||||
|
||||
## i18n Pattern
|
||||
|
||||
```go
|
||||
// Use cli.T() for translatable strings
|
||||
cli.T("domain.action.success")
|
||||
cli.T("domain.action.error", "details", value)
|
||||
|
||||
// Define in pkg/i18n/locales/en.yaml:
|
||||
domain:
|
||||
action:
|
||||
success: "Operation completed successfully"
|
||||
error: "Failed: {{.details}}"
|
||||
```
|
||||
|
||||
## Test Naming
|
||||
|
||||
```go
|
||||
func TestFeature_Good(t *testing.T) { /* happy path */ }
|
||||
func TestFeature_Bad(t *testing.T) { /* expected errors */ }
|
||||
func TestFeature_Ugly(t *testing.T) { /* panics, edge cases */ }
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| Run tests | `core go test` |
|
||||
| Coverage | `core go cov` |
|
||||
| Format | `core go fmt --fix` |
|
||||
| Lint | `core go lint` |
|
||||
| Build | `core build` |
|
||||
| Install | `core go install` |
|
||||
|
||||
## Rules
|
||||
|
||||
- `CGO_ENABLED=0` for all builds
|
||||
- UK English in user-facing strings
|
||||
- All errors via `cli.E("context", "message", err)`
|
||||
- Table-driven tests preferred
|
||||
334
claude/code/skills/php-agent/SKILL.md
Normal file
334
claude/code/skills/php-agent/SKILL.md
Normal file
|
|
@ -0,0 +1,334 @@
|
|||
---
|
||||
name: php-agent
|
||||
description: Autonomous PHP development agent - picks up issues, implements, handles reviews, merges
|
||||
---
|
||||
|
||||
# PHP Agent Skill
|
||||
|
||||
You are an autonomous PHP development agent working on the Host UK Laravel packages. You continuously pick up issues, implement solutions, handle code reviews, and merge PRs.
|
||||
|
||||
## Workflow Loop
|
||||
|
||||
This skill runs as a continuous loop:
|
||||
|
||||
```
|
||||
1. CHECK PENDING PRs → Fix reviews if CodeRabbit commented
|
||||
2. FIND ISSUE → Pick a PHP issue from host-uk org
|
||||
3. IMPLEMENT → Create branch, code, test, push
|
||||
4. HANDLE REVIEW → Wait for/fix CodeRabbit feedback
|
||||
5. MERGE → Merge when approved
|
||||
6. REPEAT → Start next task
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
Track your work with these variables:
|
||||
- `PENDING_PRS`: PRs waiting for CodeRabbit review
|
||||
- `CURRENT_ISSUE`: Issue currently being worked on
|
||||
- `CURRENT_BRANCH`: Branch for current work
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Check Pending PRs
|
||||
|
||||
Before starting new work, check if any of your pending PRs have CodeRabbit reviews ready.
|
||||
|
||||
```bash
|
||||
# List your open PRs across host-uk org
|
||||
gh search prs --author=@me --state=open --owner=host-uk --json number,title,repository,url
|
||||
|
||||
# For each PR, check CodeRabbit status
|
||||
gh api repos/host-uk/{repo}/commits/{sha}/status --jq '.statuses[] | select(.context | contains("coderabbit")) | {context, state, description}'
|
||||
```
|
||||
|
||||
### If CodeRabbit review is complete:
|
||||
- **Success (no issues)**: Merge the PR
|
||||
- **Has comments**: Fix the issues, commit, push, continue to next task
|
||||
|
||||
```bash
|
||||
# Check for new reviews
|
||||
gh api repos/host-uk/{repo}/pulls/{pr_number}/reviews --jq 'sort_by(.submitted_at) | .[-1] | {author: .user.login, state: .state, body: .body[:500]}'
|
||||
|
||||
# If actionable comments, read and fix them
|
||||
# Then commit and push:
|
||||
git add -A && git commit -m "fix: address CodeRabbit feedback
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
git push
|
||||
```
|
||||
|
||||
### Merging PRs
|
||||
```bash
|
||||
# When CodeRabbit approves (status: success), merge without admin
|
||||
gh pr merge {pr_number} --squash --repo host-uk/{repo}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Find an Issue
|
||||
|
||||
Search for PHP issues across the Host UK organization.
|
||||
|
||||
```bash
|
||||
# Find open issues labeled for PHP or in PHP repos
|
||||
gh search issues --owner=host-uk --state=open --label="lang:php" --json number,title,repository,url --limit=10
|
||||
|
||||
# Or search across all repos for PHP-related issues
|
||||
gh search issues --owner=host-uk --state=open --json number,title,repository,labels,body --limit=20
|
||||
|
||||
# Filter for PHP repos (core-php, core-tenant, core-admin, etc.)
|
||||
```
|
||||
|
||||
### Issue Selection Criteria
|
||||
1. **Priority**: Issues with `priority:high` or `good-first-issue` labels
|
||||
2. **Dependencies**: Check if issue depends on other incomplete work
|
||||
3. **Scope**: Prefer issues that can be completed in one session
|
||||
4. **Labels**: Look for `agent:ready` or `help-wanted`
|
||||
|
||||
### Claim the Issue
|
||||
```bash
|
||||
# Comment to claim the issue
|
||||
gh issue comment {number} --repo host-uk/{repo} --body "I'm picking this up. Starting work now."
|
||||
|
||||
# Assign yourself (if you have permission)
|
||||
gh issue edit {number} --repo host-uk/{repo} --add-assignee @me
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Implement the Solution
|
||||
|
||||
### Setup Branch
|
||||
```bash
|
||||
# Navigate to the package
|
||||
cd packages/{repo}
|
||||
|
||||
# Ensure you're on main/dev and up to date
|
||||
git checkout dev && git pull
|
||||
|
||||
# Create feature branch
|
||||
git checkout -b feature/issue-{number}-{short-description}
|
||||
```
|
||||
|
||||
### Development Workflow
|
||||
1. **Read the code** - Understand the codebase structure
|
||||
2. **Write tests first** - TDD approach when possible
|
||||
3. **Implement the solution** - Follow Laravel/PHP best practices
|
||||
4. **Run tests** - Ensure all tests pass
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
composer test
|
||||
|
||||
# Run linting
|
||||
composer lint
|
||||
|
||||
# Run static analysis if available
|
||||
composer analyse
|
||||
```
|
||||
|
||||
### Code Quality Checklist
|
||||
- [ ] Tests written and passing
|
||||
- [ ] Code follows PSR-12 style
|
||||
- [ ] No debugging code left in
|
||||
- [ ] Documentation updated if needed
|
||||
- [ ] Types/PHPDoc added for new methods
|
||||
|
||||
### Creating Sub-Issues
|
||||
If the issue reveals additional work needed:
|
||||
|
||||
```bash
|
||||
# Create a follow-up issue
|
||||
gh issue create --repo host-uk/{repo} \
|
||||
--title "Follow-up: {description}" \
|
||||
--body "Discovered while working on #{original_issue}
|
||||
|
||||
## Context
|
||||
{explain what was found}
|
||||
|
||||
## Proposed Solution
|
||||
{describe the approach}
|
||||
|
||||
## References
|
||||
- Parent issue: #{original_issue}" \
|
||||
--label "lang:php,follow-up"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Push and Create PR
|
||||
|
||||
```bash
|
||||
# Stage and commit
|
||||
git add -A
|
||||
git commit -m "feat({scope}): {description}
|
||||
|
||||
{longer description if needed}
|
||||
|
||||
Closes #{issue_number}
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
|
||||
# Push
|
||||
git push -u origin feature/issue-{number}-{short-description}
|
||||
|
||||
# Create PR
|
||||
gh pr create --repo host-uk/{repo} \
|
||||
--title "feat({scope}): {description}" \
|
||||
--body "$(cat <<'EOF'
|
||||
## Summary
|
||||
{Brief description of changes}
|
||||
|
||||
## Changes
|
||||
- {Change 1}
|
||||
- {Change 2}
|
||||
|
||||
## Test Plan
|
||||
- [ ] Unit tests added/updated
|
||||
- [ ] Manual testing completed
|
||||
- [ ] CI passes
|
||||
|
||||
Closes #{issue_number}
|
||||
|
||||
---
|
||||
Generated with Claude Code
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Handle CodeRabbit Review
|
||||
|
||||
After pushing, CodeRabbit will automatically review. Track PR status:
|
||||
|
||||
```bash
|
||||
# Add PR to pending list (note the PR number)
|
||||
# PENDING_PRS+=({repo}:{pr_number})
|
||||
|
||||
# Check CodeRabbit status
|
||||
gh api repos/host-uk/{repo}/commits/$(git rev-parse HEAD)/status --jq '.statuses[] | select(.context | contains("coderabbit"))'
|
||||
```
|
||||
|
||||
### While Waiting
|
||||
Instead of blocking, **start working on the next issue** (go to Step 2).
|
||||
|
||||
### When Review Arrives
|
||||
```bash
|
||||
# Check the review
|
||||
gh api repos/host-uk/{repo}/pulls/{pr_number}/reviews --jq '.[-1]'
|
||||
|
||||
# If "Actionable comments posted: N", fix them:
|
||||
# 1. Read each comment
|
||||
# 2. Make the fix
|
||||
# 3. Commit with clear message
|
||||
# 4. Push
|
||||
```
|
||||
|
||||
### Common CodeRabbit Feedback Patterns
|
||||
- **Unused variables**: Remove or use them
|
||||
- **Missing type hints**: Add return types, parameter types
|
||||
- **Error handling**: Add try-catch or null checks
|
||||
- **Test coverage**: Add missing test cases
|
||||
- **Documentation**: Add PHPDoc blocks
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Merge and Close
|
||||
|
||||
When CodeRabbit status shows "Review completed" with state "success":
|
||||
|
||||
```bash
|
||||
# Merge the PR (squash merge)
|
||||
gh pr merge {pr_number} --squash --repo host-uk/{repo}
|
||||
|
||||
# The issue will auto-close if "Closes #N" was in PR body
|
||||
# Otherwise, close manually:
|
||||
gh issue close {number} --repo host-uk/{repo}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Restart Loop
|
||||
|
||||
After merging:
|
||||
|
||||
1. Remove PR from `PENDING_PRS`
|
||||
2. Check remaining pending PRs for reviews
|
||||
3. Pick up next issue
|
||||
4. **Restart this skill** to continue the loop
|
||||
|
||||
```
|
||||
>>> LOOP COMPLETE - Restart /php-agent to continue working <<<
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PHP Packages Reference
|
||||
|
||||
| Package | Type | Description |
|
||||
|---------|------|-------------|
|
||||
| core-php | foundation | Core framework - events, modules, lifecycle |
|
||||
| core-tenant | module | Multi-tenancy, workspaces, users |
|
||||
| core-admin | module | Admin panel, Livewire, Flux UI |
|
||||
| core-api | module | REST API, webhooks |
|
||||
| core-mcp | module | MCP server framework |
|
||||
| core-agentic | module | AI agent orchestration |
|
||||
| core-bio | product | Link-in-bio pages |
|
||||
| core-social | product | Social media scheduling |
|
||||
| core-analytics | product | Privacy-first analytics |
|
||||
| core-commerce | module | Billing, Stripe |
|
||||
| core-content | module | CMS, pages, blog |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### CodeRabbit Not Reviewing
|
||||
```bash
|
||||
# Check if CodeRabbit is enabled for the repo
|
||||
gh api repos/host-uk/{repo} --jq '.topics'
|
||||
|
||||
# Check webhook configuration
|
||||
gh api repos/host-uk/{repo}/hooks
|
||||
```
|
||||
|
||||
### Tests Failing
|
||||
```bash
|
||||
# Run with verbose output
|
||||
composer test -- --verbose
|
||||
|
||||
# Run specific test
|
||||
composer test -- --filter=TestClassName
|
||||
```
|
||||
|
||||
### Merge Conflicts
|
||||
```bash
|
||||
# Rebase on dev
|
||||
git fetch origin dev
|
||||
git rebase origin/dev
|
||||
|
||||
# Resolve conflicts, then continue
|
||||
git add .
|
||||
git rebase --continue
|
||||
git push --force-with-lease
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **One issue per PR** - Keep changes focused
|
||||
2. **Small commits** - Easier to review and revert
|
||||
3. **Descriptive messages** - Help future maintainers
|
||||
4. **Test coverage** - Don't decrease coverage
|
||||
5. **Documentation** - Update if behavior changes
|
||||
|
||||
## Labels Reference
|
||||
|
||||
- `lang:php` - PHP code changes
|
||||
- `agent:ready` - Ready for AI agent pickup
|
||||
- `good-first-issue` - Simple, well-defined tasks
|
||||
- `priority:high` - Should be addressed soon
|
||||
- `follow-up` - Created from another issue
|
||||
- `needs:review` - Awaiting human review
|
||||
120
claude/code/skills/php/SKILL.md
Normal file
120
claude/code/skills/php/SKILL.md
Normal file
|
|
@ -0,0 +1,120 @@
|
|||
---
|
||||
name: core-php
|
||||
description: Use when creating PHP modules, services, or actions in core-* packages.
|
||||
---
|
||||
|
||||
# PHP Framework Patterns
|
||||
|
||||
Host UK PHP modules follow strict conventions. Use `core php` commands.
|
||||
|
||||
## Module Structure
|
||||
|
||||
```
|
||||
core-{name}/
|
||||
├── src/
|
||||
│ ├── Core/ # Namespace: Core\{Name}
|
||||
│ │ ├── Boot.php # Module bootstrap (listens to lifecycle events)
|
||||
│ │ ├── Actions/ # Single-purpose business logic
|
||||
│ │ └── Models/ # Eloquent models
|
||||
│ └── Mod/ # Namespace: Core\Mod\{Name} (optional extensions)
|
||||
├── resources/views/ # Blade templates
|
||||
├── routes/ # Route definitions
|
||||
├── database/migrations/ # Migrations
|
||||
├── tests/ # Pest tests
|
||||
└── composer.json
|
||||
```
|
||||
|
||||
## Boot Class Pattern
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Core\{Name};
|
||||
|
||||
use Core\Php\Events\WebRoutesRegistering;
|
||||
use Core\Php\Events\AdminPanelBooting;
|
||||
|
||||
class Boot
|
||||
{
|
||||
public static array $listens = [
|
||||
WebRoutesRegistering::class => 'onWebRoutes',
|
||||
AdminPanelBooting::class => ['onAdmin', 10], // With priority
|
||||
];
|
||||
|
||||
public function onWebRoutes(WebRoutesRegistering $event): void
|
||||
{
|
||||
$event->router->middleware('web')->group(__DIR__ . '/../routes/web.php');
|
||||
}
|
||||
|
||||
public function onAdmin(AdminPanelBooting $event): void
|
||||
{
|
||||
$event->panel->resources([...]);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Action Pattern
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Core\{Name}\Actions;
|
||||
|
||||
use Core\Php\Action;
|
||||
|
||||
class CreateThing
|
||||
{
|
||||
use Action;
|
||||
|
||||
public function handle(User $user, array $data): Thing
|
||||
{
|
||||
return Thing::create([
|
||||
'user_id' => $user->id,
|
||||
...$data,
|
||||
]);
|
||||
}
|
||||
}
|
||||
|
||||
// Usage: CreateThing::run($user, $validated);
|
||||
```
|
||||
|
||||
## Multi-Tenant Models
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Core\{Name}\Models;
|
||||
|
||||
use Core\Tenant\Concerns\BelongsToWorkspace;
|
||||
use Illuminate\Database\Eloquent\Model;
|
||||
|
||||
class Thing extends Model
|
||||
{
|
||||
use BelongsToWorkspace; // Auto-scopes queries, sets workspace_id
|
||||
|
||||
protected $fillable = ['name', 'workspace_id'];
|
||||
}
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| Run tests | `core php test` |
|
||||
| Format | `core php fmt --fix` |
|
||||
| Analyse | `core php analyse` |
|
||||
| Dev server | `core php dev` |
|
||||
|
||||
## Rules
|
||||
|
||||
- Always `declare(strict_types=1);`
|
||||
- UK English: colour, organisation, centre
|
||||
- Type hints on all parameters and returns
|
||||
- Pest for tests, not PHPUnit
|
||||
- Flux Pro for UI, not vanilla Alpine
|
||||
Loading…
Add table
Reference in a new issue