1. Language and ecosystem: Identify from manifest files (package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, build.gradle, etc.)
2. Package manager: npm/yarn/pnpm, pip/poetry/uv, go mod, cargo, maven/gradle
3. Framework: Detect from dependencies and config files (Next.js, Django, Spring Boot, Rails, etc.)
4. Build system: Webpack, Vite, Turborepo, Nx, Gradle, Maven, Make, etc.
5. Test setup: Test framework, runner command, test config files
6. Lint/format tools: ESLint, Prettier, Ruff, Black, golangci-lint, etc.
7. Containerization: Dockerfile presence, docker-compose, Kubernetes manifests
8. Infrastructure as Code: Terraform, Pulumi, CloudFormation, CDK
9. Monorepo signals: Multiple package.json files, workspace configs, Nx/Turborepo/Lerna config
10. Deployment targets: Cloud provider configs, serverless.yml, Kubernetes, Vercel/Netlify config
11. Existing workflows: Current .github/workflows/*.yml files
12. Branch strategy: Default branch (main/master), protected branches, release branch patterns
13. Release patterns: Tags, GitHub Releases, changelogs, version files

• Read README.md and CLAUDE.md first (if they exist)
• Read manifest files (package.json, pyproject.toml, go.mod, etc.)
• Scan

  .github/

  directory for existing workflows, actions, dependabot config
• Check for Dockerfiles, docker-compose files, Kubernetes manifests
• Look for IaC files (*.tf, serverless.yml, template.yaml)
• Check for monorepo indicators (workspaces, nx.json, turbo.json, lerna.json)
• Read 2-3 key source files to understand project patterns
• Check existing CI config from other systems (.circleci/, Jenkinsfile, .gitlab-ci.yml, .travis.yml)

.github/workflows/*.yml

1. Read it fully. Parse the YAML structure: triggers, permissions, jobs, steps, secrets usage, caching, matrix strategies.
2. Classify its purpose: CI (test/lint/build), CD (deploy), Release (publish/tag), Maintenance (dependabot, stale issues), Scheduled (cron jobs).
3. Note its conventions: naming style, job naming, step naming, comment style, environment variable patterns.
4. Assess security posture: permissions declared? Actions pinned by SHA? Secrets handling? Fork protections? OIDC usage?
5. Assess performance: caching used? Unnecessary steps? Job parallelism? Matrix strategy? Concurrency groups?

• File naming: kebab-case? snake_case? What prefix/suffix patterns?
• Job naming: How are jobs named? Descriptive or terse?
• Step naming: Named steps or anonymous? Style of names?
• Comment style: Are inline comments used? YAML comments?
• Secret naming: Convention for secret names (SCREAMING_SNAKE, etc.)?
• Environment patterns: How environments are used (if at all)?

1. CI workflow (pull request validation):
   • Lint/format check
   • Type check (if applicable)
   • Unit tests
   • Build verification
2. CI workflow (main branch):
   • Everything in PR CI, plus:
   • Integration tests (if applicable)
   • Artifact building
   • Trigger CD (if applicable)
3. CD workflow (if deployment target exists):
   • Build artifacts/containers
   • Deploy to environments (staging, production)
   • Environment protection rules
4. Release workflow (if library or publishable):
   • Version bumping
   • Package publishing (npm, PyPI, Maven, crates.io)
   • GitHub Release creation
5. Maintenance workflows (recommended):
   • Dependabot configuration
   • Stale issue/PR management
   • Scheduled security scans

1. Identify which EXISTING workflows might be affected (shared secrets, concurrency groups, deployment targets)
2. Identify the NEW workflow to create
3. For existing workflows, specify ONLY what changes (if anything)

Workflow Delta Plan
- .github/workflows/ci.yml — KEEP (no changes needed)
- .github/workflows/deploy.yml — MODIFY: add staging environment before prod
- .github/workflows/docker.yml — CREATE: Docker build + push to GHCR

1. List all issues found in Phase 1 with severity
2. Propose fixes grouped by category (Security > Performance > Maintenance)
3. For each workflow: KEEP (as-is), EDIT (fix issues), REWRITE (replace), DELETE (remove dead workflow)
4. Present to user for approval

Audit Findings & Plan
  ci.yml:
    - [Critical] Actions not pinned to SHA → EDIT: pin all actions
    - [High] No permissions declared → EDIT: add least-privilege permissions
    - [Medium] No dependency caching → EDIT: add cache configuration
  deploy.yml:
    - [High] Uses long-lived AWS keys → EDIT: migrate to OIDC
    - [Low] No concurrency group → EDIT: add concurrency
  old-ci.yml:
    - [Low] Duplicate of ci.yml → DELETE

1. Read the existing workflow fully (done in Phase 1)
2. Identify what to PRESERVE (working trigger logic, secrets, custom scripts)
3. Identify what to REPLACE (insecure patterns, poor performance, outdated actions)
4. Identify what to ADD (missing security, caching, concurrency)
5. Present the plan

Rewrite Plan: ci.yml
  PRESERVE: Trigger logic (push/PR), test matrix (Node 18/20), deploy job dependency
  REPLACE:  Unpinned actions (pin to SHA), npm install (use npm ci + caching),
            missing permissions (add least-privilege)
  ADD:      Concurrency group, artifact upload for test reports, type checking step

1. Read the source CI config (.circleci/config.yml, Jenkinsfile, .gitlab-ci.yml)
2. Map each job/stage to a GitHub Actions equivalent
3. Identify feature gaps (some CI features don't map 1:1)
4. Plan the migration as a set of new workflows

Migration Plan: CircleCI → GitHub Actions
  CircleCI build job → .github/workflows/ci.yml (lint + test + build)
  CircleCI deploy job → .github/workflows/deploy.yml (with environment protection)
  CircleCI scheduled scan → .github/workflows/security.yml (cron schedule)
  Gap: CircleCI orbs used → Replace with equivalent GitHub Actions

1. CI workflow first (validates that the build/test pipeline works)
2. CD workflow (deployment depends on CI)
3. Release workflow (publishing depends on build)
4. Maintenance workflows (dependabot, security scans)

1. Select template: Choose from references/workflow-templates.md based on language/ecosystem detected in Phase 0.
2. Customize for project: Replace template placeholders with actual commands, paths, versions from the repository profile.
3. Apply security hardening: Follow every rule in references/security-hardening.md:
   • Set explicit

     permissions:

     (least privilege)
   • Pin all actions to full SHA
   • Use OIDC for cloud auth where possible
   • Protect secrets from fork exposure
   • Guard against script injection
4. Add performance optimization:
   • Add dependency caching (use setup action's built-in cache where available)
   • Add concurrency groups to cancel stale runs
   • Use matrix strategy for multi-version testing
   • Add path filters to avoid unnecessary runs
5. Verify YAML syntax: Ensure valid YAML, proper indentation, correct GitHub Actions syntax.
6. Add inline comments: Explain non-obvious choices (why a specific SHA, why a particular cache key, why a permission).

1. Re-read the workflow. Confirm your understanding from Phase 1.
2. Apply only planned changes. Follow the delta plan from Phase 2. Do NOT restructure, restyle, or "improve" sections outside scope.
3. Match existing conventions. Use the same naming style, comment style, and patterns discovered in Phase 1.
4. Preserve working logic. Trigger conditions, environment variables, secrets references, and custom scripts survive unless explicitly marked for change.
5. Verify every edit. Each changed action version, command, or path must be verified against the codebase.
6. Minimize diff. Change only what needs changing. Smaller diffs are easier to review.

• Edit, don't rewrite. Unless the user requests a rewrite, modify the existing workflow surgically. Fix the specific issues; leave working steps alone.
• Match existing style. If existing workflows use

  name: Build and Test

  for jobs, continue that pattern. Do NOT switch to

  name: build-and-test

  because you prefer it.
• Preserve structure. Keep the existing job ordering unless it's part of the planned changes.
• Never silently remove steps. If a step needs removal, note it in your plan and confirm with the user. A step that looks unnecessary may have a non-obvious purpose.
• Refactor only what you're asked to change. Do NOT improve adjacent workflows, fix unrelated issues, or add features not in the plan.

1. Create from the approved plan. Write the new version using the PRESERVE/REPLACE/ADD breakdown from Phase 2.
2. Start from the template in references/workflow-templates.md, then transplant preserved logic into the new structure.
3. For preserved content: Keep trigger logic, secrets, and custom scripts intact.
4. For replaced content: Write fresh from repository analysis.
5. For added content: Follow greenfield per-workflow process.
6. Present the full new workflow for review before replacing.

Triggers section — always explicit, never use defaults

• Valid YAML: Proper indentation, no syntax errors
• Triggers correct: Events match intended behavior (push, PR, tag, schedule)
• Permissions declared: Explicit

  permissions:

  at workflow or job level
• Least privilege: No unnecessary write permissions
• Actions pinned: All

  uses:

  reference full SHA (not tags or branches)
• Commands exist: Every

  run:

  command references valid scripts, tools, and paths
• Secrets referenced correctly: All

  ${{ secrets.* }}

  reference expected secret names
• Caching configured: Dependencies are cached where possible
• Concurrency set: Workflow has concurrency group to prevent queue buildup
• Branch filters correct: Push/PR triggers reference correct branch names
• Path filters appropriate: Path-based triggers match actual project structure
• Matrix strategy sensible: Tested versions are current and supported
• Artifact handling correct: Upload/download artifact names are consistent
• Environment protection: Deploy jobs reference proper environments
• No script injection: Untrusted input is never used in

  run:

  directly
• No hardcoded secrets: No credentials in workflow files

• Preserved logic intact: Trigger conditions, secrets, and custom scripts from existing workflows were not lost
• Conventions maintained: Naming, commenting, and structure style match the rest of the existing workflows
• No unplanned changes: Only the sections identified in the delta plan were modified
• No steps silently removed: Every removal was in the approved plan
• Diff is minimal: Changes are surgical, not a full rewrite (unless Targeted Rewrite was the chosen workflow type)

1. Validate YAML syntax by reading it carefully for indentation and structure issues
2. Check all referenced paths exist in the repository (scripts, config files, directories)
3. Verify action references are valid (action exists, SHA is real)
4. Verify commands match the project's actual tools and scripts (check package.json scripts, Makefile targets, etc.)
5. Check secret names match what the project expects (documented in README or existing workflows)
6. Simulate trigger scenarios mentally: what happens on PR, push to main, tag push, schedule?
7. (Brownfield) Compare against original to confirm only planned changes were made

• Version workflows alongside code. All workflows live in

  .github/workflows/

  .
• Review workflow changes in PRs. Use CODEOWNERS on

  .github/

  to require review for workflow changes.
• Keep actions updated. Use Dependabot for GitHub Actions ecosystem updates.
• Delete dead workflows. Unused workflows create confusion and security risk.
• Document non-obvious choices. Inline comments explain WHY, not WHAT.

1. Branch protection rules: Require CI to pass before merge
2. CODEOWNERS: Protect

   .github/

   directory
3. Dependabot: Keep actions and dependencies updated
4. actionlint: Add as a CI step or pre-commit hook
5. Environment protection rules: Require approval for production deploys

• Unpinned actions: Using

  @v4

  instead of

  @sha

  — supply chain attack vector
• Missing permissions: No

  permissions:

  block — defaults to overly broad access
• Script injection: Using

  ${{ github.event.* }}

  directly in

  run:

  blocks
• Long-lived credentials: Storing AWS/GCP keys as secrets instead of using OIDC
• Fork secret exposure: Running

  pull_request_target

  with checkout of PR code
• Overly broad

  GITHUB_TOKEN

  : Granting write permissions when read suffices

• No caching: Reinstalling dependencies from scratch every run
• No concurrency groups: Queue buildup on rapid pushes
• Monolithic workflows: One huge workflow instead of parallel jobs
• Unnecessary triggers: Running full CI on docs-only changes
• Missing path filters: Every push triggers every workflow regardless of changes
• Excessive matrix: Testing on 12 OS/version combos when 4 would suffice

• Workflow sprawl: 20 small workflow files with overlapping triggers
• Duplicate logic: Same steps copy-pasted across workflows (use reusable workflows)
• Missing

  needs:

  : Jobs that should be sequential running in parallel
• No environment protection: Deploy to production without approval gates
• No Dependabot: Actions and dependencies never updated

• Treating first draft as final: Always verify against the codebase
• Ignoring existing workflows: Not reading current workflows before modifying
• Over-engineering: Adding complex matrix builds for a single-language project
• Premature optimization: Adding self-hosted runners before measuring need

• Repository discovery: See references/repo-discovery.md for deterministic repository analysis: language detection, ecosystem identification, deployment target detection, and monorepo discovery
• Workflow templates: See references/workflow-templates.md for complete YAML templates per ecosystem: Node.js, Python, Go, Rust, Java, Docker, Terraform, and monorepo configurations
• Security hardening: See references/security-hardening.md for permissions model, action pinning with current SHAs, OIDC configuration, secret management, fork protection, and script injection prevention
• Pipeline patterns: See references/pipeline-patterns.md for CI/CD patterns: caching strategies, matrix builds, concurrency groups, reusable workflows, monorepo change detection, deployment strategies, release automation, and scheduled pipelines