Phase 1: Core Foundation - Detailed Work Plan

Status: ✅ COMPLETE Started: 2025-11-06 Completed: 2025-11-06 Duration: Week 1 Last Updated: 2025-11-06

🎯 Phase 1 Objectives

Build the foundational GitHub Actions infrastructure that enables:

✅ Automated quality checks (lint, typecheck, test)
✅ PR validation and protection
✅ Plan-to-issues conversion (max 10 tasks)
✅ Auto-branch creation from issues
✅ PR lifecycle tracking and project board sync
✅ Production release gates
✅ Repository bootstrapping

📊 Implementation Strategy

Order of Implementation (Dependency-Based)

Foundation Layer (No Dependencies)
├── 1. Composite Actions (utilities first)
│   ├── fork-safety
│   ├── rate-limit-check
│   ├── setup-node-pnpm
│   ├── project-sync
│   └── quality-gates
│
├── 2. Configuration Templates
│   ├── commit-template.txt
│   ├── CODEOWNERS
│   ├── pull_request_template.md
│   ├── ISSUE_TEMPLATE/plan-task.md
│   ├── ISSUE_TEMPLATE/manual-task.md
│   └── dependabot.yml
│
└── 3. Core Workflows (build on composites)
    ├── bootstrap.yml (independent, run first)
    ├── reusable-pr-checks.yml (foundation for others)
    ├── pr-into-dev.yml (uses reusable-pr-checks)
    ├── dev-to-main.yml (independent)
    ├── claude-plan-to-issues.yml (uses project-sync)
    ├── create-branch-on-issue.yml (uses project-sync)
    ├── pr-status-sync.yml (uses project-sync)
    └── release-status-sync.yml (uses project-sync)

Rationale: Build composites first → they're dependencies for workflows → enables testing as we go

🔧 Work Packages

Work Package 1: Composite Actions (Priority: CRITICAL)

Estimated Time: 3-4 hours Dependencies: None Deliverables: 5 reusable composite actions

WP1.1: `fork-safety` (30 minutes)

Purpose: Detect fork PRs to skip write operations

Tasks:

Create .github/actions/fork-safety/action.yml
Implement fork detection logic
Add outputs: is-fork, should-skip-writes
Test with mock fork PR data
Document usage in action.yml

Acceptance Criteria:

✅ Correctly identifies fork PRs
✅ Returns boolean outputs
✅ <1 second execution time
✅ Clear documentation

Testing:

# Test command
is_fork=$(gh api repos/:owner/:repo/pulls/:pr_number --jq '.head.repo.fork')

WP1.2: `rate-limit-check` (45 minutes)

Purpose: Circuit breaker to prevent API exhaustion

Tasks:

Create .github/actions/rate-limit-check/action.yml
Query GitHub API rate limit status
Implement threshold check (default: 50 remaining)
Add outputs: can-proceed, remaining, reset-time
Add warning logs when below threshold
Test with current API limits
Document usage and thresholds

Acceptance Criteria:

✅ Accurate rate limit detection
✅ Configurable threshold
✅ Clear outputs for conditionals
✅ <1 second execution time
✅ Helpful warning messages

Testing:

# Test command
gh api rate_limit --jq '.resources.core'

WP1.3: `setup-node-pnpm` (1 hour)

Purpose: Fast, cached Node.js and pnpm setup

Tasks:

Create .github/actions/setup-node-pnpm/action.yml
Add inputs: node-version, pnpm-version, working-directory
Implement Node.js setup with caching
Implement pnpm setup with caching
Implement node_modules cache restoration
Add cache miss fallback (fresh install)
Test cache hit vs miss scenarios
Document cache keys and behavior

Acceptance Criteria:

✅ Cache hit reduces install time by 90%+
✅ Handles cache miss gracefully
✅ Supports custom working directories
✅ Works with monorepos
✅ Clear cache key strategy

Cache Key Pattern:

${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}

Testing:

Run twice: first (cache miss), second (cache hit)
Compare execution times

WP1.4: `project-sync` (1.5 hours) ⚠️ Most Complex

Purpose: GitHub Projects v2 GraphQL sync helper

Tasks:

Acceptance Criteria:

✅ Successfully syncs issue to project status
✅ Handles rate limits with backoff
✅ Idempotent (safe to run multiple times)
✅ Clear error messages
✅ <5 seconds average execution time
✅ Works with Projects v2 only

GraphQL Queries (reference implementation):

# Get Project ID
query($url: URI!) {
  resource(url: $url) {
    ... on ProjectV2 {
      id
    }
  }
}

# Get Field ID
query($projectId: ID!) {
  node(id: $projectId) {
    ... on ProjectV2 {
      fields(first: 20) {
        nodes {
          ... on ProjectV2SingleSelectField {
            id
            name
            options {
              id
              name
            }
          }
        }
      }
    }
  }
}

# Update Item Status
mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
  updateProjectV2ItemFieldValue(
    input: {
      projectId: $projectId
      itemId: $itemId
      fieldId: $fieldId
      value: { singleSelectOptionId: $optionId }
    }
  ) {
    projectV2Item {
      id
    }
  }
}

Testing:

Create test issue
Sync to "Ready" status
Verify in project board
Re-run (test idempotency)

WP1.5: `quality-gates` (45 minutes)

Purpose: Orchestrated quality check runner

Tasks:

Acceptance Criteria:

✅ All checks execute correctly
✅ Fail-fast mode works
✅ Clear markdown summary
✅ Exit code reflects overall pass/fail
✅ Works with custom npm scripts

Testing:

Mock package.json with test scripts
Run with all checks
Verify summary output

Work Package 2: Configuration Templates (Priority: HIGH)

Estimated Time: 2 hours Dependencies: None Deliverables: 6 configuration files

WP2.1: `commit-template.txt` (15 minutes)

Tasks:

Create .github/commit-template.txt
Add conventional commit structure
Add context, testing, reviewers sections
Document usage in comments
Validate format

Template Structure:

<type>(<scope>): <subject>

## Context

## Testing

## Reviewers

WP2.2: `CODEOWNERS` (15 minutes)

Tasks:

Create .github/CODEOWNERS
Add default owners
Add path-specific owners:
- /.github/ (workflows team)
- /.claude/ (automation team)
- /docs/ (docs team)
- /setup/ (devops team)
Document ownership rules

WP2.3: `pull_request_template.md` (30 minutes)

Tasks:

Create .github/pull_request_template.md
Add sections:
- Summary
- Type of change (checkboxes)
- Related issues (with enforcement note)
- Testing checklist
- Code quality checklist
- Platform (web/mobile/both)
- Breaking changes
- Screenshots (optional)
Add helpful comments
Validate markdown

WP2.4: `ISSUE_TEMPLATE/plan-task.md` (20 minutes)

Tasks:

Create .github/ISSUE_TEMPLATE/plan-task.md
Add YAML frontmatter:
- name: Plan Task
- about: Auto-generated from Claude plan
- labels: claude-code, status:ready
Add template sections:
- Task description
- Acceptance criteria
- Priority
- Platform
- Dependencies
Use template variables for automation
Validate format

WP2.5: `ISSUE_TEMPLATE/manual-task.md` (20 minutes)

Tasks:

Create .github/ISSUE_TEMPLATE/manual-task.md
Add YAML frontmatter:
- name: Manual Task
- about: User-created task
- labels: status:to-triage
Add clear prompts for:
- Description
- Acceptance criteria
- Priority selection
- Platform selection
- Type selection
Validate format

WP2.6: `dependabot.yml` (20 minutes)

Tasks:

Create .github/dependabot.yml
Configure npm updates (weekly)
Configure GitHub Actions updates (weekly)
Configure Gradle updates (weekly, if mobile)
Set sensible commit message prefix
Add labels for automerge detection
Document configuration

Work Package 3: Core Workflows (Priority: CRITICAL)

Estimated Time: 6-8 hours Dependencies: WP1 (composites), WP2 (templates) Deliverables: 8 GitHub Actions workflows

WP3.1: `bootstrap.yml` (45 minutes)

Purpose: One-time repository setup Dependencies: None (independent)

Tasks:

Create .github/workflows/bootstrap.yml
Add trigger: workflow_dispatch only
Implement label creation:
- Status labels (ready, in-progress, in-review, to-deploy)
- Type labels (feature, fix, hotfix, docs, refactor, test)
- Platform labels (web, mobile, fullstack)
- Priority labels (critical, high, medium, low)
- Meta label (claude-code)
Add project board validation
Add secrets validation (ANTHROPIC_API_KEY, PROJECT_URL)
Add idempotency (safe to re-run)
Generate summary output
Test manually
Document usage

Acceptance Criteria:

✅ Creates all required labels
✅ Validates project board exists
✅ Validates secrets present
✅ Safe to run multiple times
✅ Clear output summary

Testing:

gh workflow run bootstrap.yml
gh run watch

WP3.2: `reusable-pr-checks.yml` (1.5 hours)

Purpose: DRY quality checks for all PRs Dependencies: setup-node-pnpm, quality-gates

Tasks:

Acceptance Criteria:

✅ Can be called by other workflows
✅ Mobile checks only run when needed
✅ Caching reduces run time 50%+
✅ Completes in <2 minutes typical case
✅ Clear error messages

Testing:

Create test caller workflow
Trigger with different inputs
Verify conditional execution

WP3.3: `pr-into-dev.yml` (1 hour)

Purpose: Validate feature PRs before dev merge Dependencies: reusable-pr-checks, fork-safety

Tasks:

Acceptance Criteria:

✅ Only validates PRs to dev
✅ Only accepts feature/fix/hotfix branches
✅ Blocks PRs without linked issues
✅ Validates conventional commit titles
✅ Fork PRs skip write operations

Testing:

Create test PR to dev
Test with/without linked issue
Test with invalid commit title

WP3.4: `dev-to-main.yml` (1 hour)

Purpose: Release gates for production Dependencies: None (independent checks)

Tasks:

Create .github/workflows/dev-to-main.yml
Add trigger: pull_request (opened, synchronize)
Add branch filters: base=main, head=dev only
Set permissions (contents: read, pull-requests: write)
Add jobs:
- build-prod (production build validation)
- smoke-tests (critical path tests)
- security-quickscan (non-blocking audit)
- deployment-readiness (checklist validation)
Make security scan continue-on-error: true
Add deployment trigger (conditional on merge)
Test with sample PR
Document release process

Acceptance Criteria:

✅ Only runs for dev → main PRs
✅ Production build succeeds
✅ Smoke tests pass
✅ Security scan informational only
✅ Deployment triggered on merge

Testing:

Create test PR dev → main
Verify all jobs run
Verify security scan doesn't block

WP3.5: `claude-plan-to-issues.yml` (2 hours) ⚠️ Most Complex

Purpose: Convert Claude plans to GitHub issues (max 10) Dependencies: project-sync, rate-limit-check

Tasks:

Plan JSON Schema:

{
  "milestone": "Sprint 1",
  "tasks": [
    {
      "title": "Task title",
      "description": "Detailed description",
      "acceptanceCriteria": ["Criterion 1", "Criterion 2"],
      "priority": "high",
      "type": "feature",
      "platform": "web",
      "dependencies": []
    }
  ]
}

Acceptance Criteria:

✅ Max 10 issues per execution
✅ All issues have correct labels
✅ Milestone created and assigned
✅ Dependencies linked correctly
✅ Added to project board
✅ Duplicate prevention works
✅ Rate limit protection active

Testing:

# Test with sample plan
gh workflow run claude-plan-to-issues.yml -f plan_json='{"milestone":"Test","tasks":[...]}'
gh run watch
# Verify issues created
gh issue list --label claude-code

WP3.6: `create-branch-on-issue.yml` (1 hour)

Purpose: Auto-create branches from ready issues Dependencies: project-sync, rate-limit-check

Tasks:

Branch Naming Examples:

feature/issue-123-login-ui
fix/issue-456-crash-on-startup
hotfix/issue-789-security-patch

Acceptance Criteria:

✅ Only triggers with both required labels
✅ Branch name follows convention
✅ Issue commented with instructions
✅ Project status updated
✅ No duplicate branches

Testing:

Create test issue with labels
Verify branch created
Check comment and project status

WP3.7: `pr-status-sync.yml` (1.5 hours)

Purpose: Sync PR lifecycle with issue status Dependencies: project-sync, rate-limit-check

Tasks:

Acceptance Criteria:

✅ All linked issues updated correctly
✅ No infinite loops
✅ Branch deleted after merge
✅ Draft PRs handled correctly
✅ Multiple linked issues supported

Testing:

Create PR with linked issue
Convert to draft → check status
Mark ready → check status
Merge → check status and branch

WP3.8: `release-status-sync.yml` (45 minutes)

Purpose: Close issues on production deployment Dependencies: project-sync

Tasks:

Acceptance Criteria:

✅ Only triggers on dev → main merges
✅ All linked issues closed
✅ Project status updated to "Done"
✅ Release comment added
✅ No false positives

Testing:

Create release PR (dev → main)
Merge and verify issues closed
Check project status

🧪 Testing Strategy

Per-Component Testing

Each component gets tested individually before integration:

Composite Actions:
- Unit test with mock inputs
- Verify outputs
- Check execution time
Workflows:
- Manual trigger test
- Verify triggers work correctly
- Check permissions
- Validate outputs
Integration Testing:
- End-to-end scenario testing
- Multiple components working together

Test Scenarios (Full Integration)

Scenario 1: First-Time Setup

# 1. Run bootstrap
gh workflow run bootstrap.yml

# 2. Verify labels created
gh label list

# 3. Verify project board accessible
# (manual check in UI)

Scenario 2: Plan to Deployment

# 1. Create plan and convert to issues
gh workflow run claude-plan-to-issues.yml -f plan_json='...'

# 2. Verify issues created with correct labels
gh issue list --label claude-code

# 3. Verify branches auto-created
git fetch && git branch -r

# 4. Create PR to dev
gh pr create --base dev --head feature/issue-1-test

# 5. Verify PR checks run
gh pr checks

# 6. Merge to dev
gh pr merge --squash

# 7. Create release PR (dev → main)
gh pr create --base main --head dev

# 8. Merge to main
gh pr merge --squash

# 9. Verify issues closed
gh issue list --state closed

📋 Validation Checklist

Before marking Phase 1 complete, verify:

Composite Actions ✅

All 5 actions created
All actions tested individually
All actions have clear documentation
All actions have correct permissions

Configuration Templates ✅

All 6 configs created
All configs validated (YAML syntax, markdown)
All configs have clear comments
All configs follow best practices

Core Workflows ✅

All 8 workflows created
All workflows have correct triggers
All workflows have minimal permissions
All workflows have concurrency control
All workflows have fork safety (where needed)
All workflows have rate limit protection (where needed)
All workflows tested individually
Full integration scenario tested
All workflows documented

Quality Gates ✅

Lint validation on all YAML files
Schema validation on workflows
Security scan on workflows (no secrets)
Performance checks (<2 min for PR)

Documentation ✅

CLAUDE.md updated with progress
implementation.md updated if changes
All usage documented in workflow files
README.md created (if not exists)

🚀 Execution Plan

Session 1: Composite Actions (3-4 hours)

WP1.1: fork-safety (30 min)
WP1.2: rate-limit-check (45 min)
WP1.3: setup-node-pnpm (1 hour)
Break (15 min)
WP1.4: project-sync (1.5 hours)
WP1.5: quality-gates (45 min)
Test all composites

Session 2: Configuration Templates (2 hours)

WP2.1-2.6: All configs (2 hours)
Validate all configs
Test templates manually

Session 3: Bootstrap + Reusable Checks (2.5 hours)

WP3.1: bootstrap.yml (45 min)
Test bootstrap
WP3.2: reusable-pr-checks.yml (1.5 hours)
Test reusable checks
Update CLAUDE.md

Session 4: PR Workflows (2.5 hours)

WP3.3: pr-into-dev.yml (1 hour)
WP3.4: dev-to-main.yml (1 hour)
Test both workflows
Update CLAUDE.md

Session 5: Automation Workflows (4 hours)

WP3.5: claude-plan-to-issues.yml (2 hours)
WP3.6: create-branch-on-issue.yml (1 hour)
WP3.7: pr-status-sync.yml (1.5 hours)
Test automation chain

Session 6: Release + Integration Testing (2 hours)

WP3.8: release-status-sync.yml (45 min)
Full integration testing (1 hour)
Validation checklist completion
Documentation updates
Phase 1 completion report

Total Estimated Time: 16-18 hours Target: Complete within 1 week (2-3 hours/day)

📊 Progress Tracking

Current Status

Phase 1 planning complete
Work packages defined
Testing strategy defined
Session 1: Composite Actions
Session 2: Configuration Templates
Session 3: Bootstrap + Reusable Checks
Session 4: PR Workflows
Session 5: Automation Workflows
Session 6: Release + Integration Testing

Blockers

None identified yet

Risks

GraphQL complexity in project-sync: Mitigate with clear documentation and testing
Rate limiting during testing: Mitigate with circuit breakers and delays
Projects v2 API changes: Mitigate by referencing official docs frequently

🎯 Definition of Done (Phase 1)

Phase 1 is complete when:

✅ All 5 composite actions implemented and tested
✅ All 6 configuration templates created and validated
✅ All 8 core workflows implemented and tested
✅ Full integration scenario passes end-to-end
✅ All validation checklist items completed
✅ CLAUDE.md updated with Phase 1 completion status
✅ implementation.md updated if any changes made
✅ README.md created or updated with Phase 1 features
✅ No critical bugs or blockers
✅ Ready to begin Phase 2 (Automation Layer)

📊 Completion Summary

Phase 1 Total: 19 files created (3,342 lines of code + documentation)

Session 1: Composite Actions ✅

5 composite actions created (2025-11-06)
Total: ~800 lines of reusable GitHub Actions components

Session 2: Configuration Templates ✅

6 configuration templates created (2025-11-06)
Total: ~600 lines of templates and configurations

Session 3: Core Workflows ✅

8 GitHub Actions workflows created (2025-11-06)
Total: ~3,342 lines of workflow automation

Git Commits:

Commit bf8b7e8: Phase 1 Sessions 1-2 (Composites + Configs)
Commit f16a9ec: Phase 1 Session 3 (Core Workflows)

Status: ✅ PHASE 1 COMPLETE

Completion Date: 2025-11-06 (Week 1)

Next Phase: Phase 2 - Automation Layer (See docs/PHASE2_WORKPLAN.md)

End of Phase 1 Work Plan

Uh oh!

FilesExpand file tree

PHASE1_WORKPLAN.md

Latest commit

History

PHASE1_WORKPLAN.md

File metadata and controls

Phase 1: Core Foundation - Detailed Work Plan

🎯 Phase 1 Objectives

📊 Implementation Strategy

Order of Implementation (Dependency-Based)

🔧 Work Packages

Work Package 1: Composite Actions (Priority: CRITICAL)

WP1.1: fork-safety (30 minutes)

WP1.2: rate-limit-check (45 minutes)

WP1.3: setup-node-pnpm (1 hour)

WP1.4: project-sync (1.5 hours) ⚠️ Most Complex

WP1.5: quality-gates (45 minutes)

Work Package 2: Configuration Templates (Priority: HIGH)

WP2.1: commit-template.txt (15 minutes)

WP2.2: CODEOWNERS (15 minutes)

WP2.3: pull_request_template.md (30 minutes)

WP2.4: ISSUE_TEMPLATE/plan-task.md (20 minutes)

WP2.5: ISSUE_TEMPLATE/manual-task.md (20 minutes)

WP2.6: dependabot.yml (20 minutes)

Work Package 3: Core Workflows (Priority: CRITICAL)

WP3.1: bootstrap.yml (45 minutes)

WP3.2: reusable-pr-checks.yml (1.5 hours)

WP3.3: pr-into-dev.yml (1 hour)

WP3.4: dev-to-main.yml (1 hour)

WP3.5: claude-plan-to-issues.yml (2 hours) ⚠️ Most Complex

WP3.6: create-branch-on-issue.yml (1 hour)

WP3.7: pr-status-sync.yml (1.5 hours)

WP3.8: release-status-sync.yml (45 minutes)

🧪 Testing Strategy

Per-Component Testing

Test Scenarios (Full Integration)

Scenario 1: First-Time Setup

Scenario 2: Plan to Deployment

📋 Validation Checklist

Composite Actions ✅

Configuration Templates ✅

Core Workflows ✅

Quality Gates ✅

Documentation ✅

🚀 Execution Plan

Session 1: Composite Actions (3-4 hours)

Session 2: Configuration Templates (2 hours)

Session 3: Bootstrap + Reusable Checks (2.5 hours)

Session 4: PR Workflows (2.5 hours)

Session 5: Automation Workflows (4 hours)

Session 6: Release + Integration Testing (2 hours)

📊 Progress Tracking

Current Status

Blockers

Risks

🎯 Definition of Done (Phase 1)

📊 Completion Summary

Session 1: Composite Actions ✅

Session 2: Configuration Templates ✅

Session 3: Core Workflows ✅

WP1.1: `fork-safety` (30 minutes)

WP1.2: `rate-limit-check` (45 minutes)

WP1.3: `setup-node-pnpm` (1 hour)

WP1.4: `project-sync` (1.5 hours) ⚠️ Most Complex

WP1.5: `quality-gates` (45 minutes)

WP2.1: `commit-template.txt` (15 minutes)

WP2.2: `CODEOWNERS` (15 minutes)

WP2.3: `pull_request_template.md` (30 minutes)

WP2.4: `ISSUE_TEMPLATE/plan-task.md` (20 minutes)

WP2.5: `ISSUE_TEMPLATE/manual-task.md` (20 minutes)

WP2.6: `dependabot.yml` (20 minutes)

WP3.1: `bootstrap.yml` (45 minutes)

WP3.2: `reusable-pr-checks.yml` (1.5 hours)

WP3.3: `pr-into-dev.yml` (1 hour)

WP3.4: `dev-to-main.yml` (1 hour)

WP3.5: `claude-plan-to-issues.yml` (2 hours) ⚠️ Most Complex

WP3.6: `create-branch-on-issue.yml` (1 hour)

WP3.7: `pr-status-sync.yml` (1.5 hours)

WP3.8: `release-status-sync.yml` (45 minutes)