IC SDLC Workflow

Shared standards for all IC engineers. Role-specific overrides are noted inline.

Task Pickup: Pull-Style Flow (Mandatory)

CascadeGuard uses a pull-based assignment model. Managers create tasks as unassigned todo items. You are responsible for picking work from the backlog.

Each heartbeat, after completing in-progress work:

1. Check for unassigned todo items: GET /api/companies/{companyId}/issues?status=todo and filter for items with no assigneeAgentId
2. Pick tasks that match your skills and respect your WIP limit (max 2 in-progress)
3. Use the standard checkout flow to self-assign
4. Prefer higher-priority items when multiple are available

Do NOT wait for a manager to assign work to you. If the backlog is empty, exit the heartbeat.

Workspace Isolation (Mandatory)

Applies to: Engineer-1, Engineer-2, DevSecOps Engineer

You MUST use the workspace-management skill to create an isolated worktree before starting any code work. Never work directly in the main checkout. Every task gets its own worktree under .builders/.

Procedure

1. After checkout, use the workspace-management skill to create a worktree for your issue
2. Do all code work inside the worktree
3. Commit, push, and create PRs from the worktree
4. Clean up the worktree after your PR is merged or the issue is closed

Planning Artifacts (Mandatory)

Plans and PRDs live on the filesystem in /workspace, committed via PR and linked from the Paperclip issue. NEVER write plans into Paperclip issue descriptions or issue documents.

• Plan → write to .ai/projects/{category}/{project-name}/ in the workspace root, commit, open a PR, link from the issue comment
• PRD → same location, owned by PO, not ICs

Plans must be concise. If your plan exceeds one page, the detailed requirements likely belong in a PRD.

WIP Limits (Mandatory)

Applies to: Engineer-1, Engineer-2, DevSecOps Engineer

You may have at most 2 items in in_progress at any time. Before starting a new item, complete or move an existing in-progress item to in_review, blocked, or todo. Focus on finishing work rather than starting new work.

PR-Based Workflow (Required)

All work MUST follow a PR-based review flow:

1. Branch: Create a feature branch for every task. Never commit directly to main.
2. PR: Open a GitHub PR with a clear title and description linking to the Paperclip issue.
3. Request CTO review: You MUST request review from the CTO on every PR. Use the GitHub API or gh pr edit --add-reviewer to add the CTO as reviewer. (Full-Stack Engineer and Lead Platform Engineer: skip this step — submit directly for board review.)
4. Review: Set the issue to in_review and leave it for board review. Do not merge.
5. Merge: Only the board merges PRs after review.

One PR Per Ticket (Required)

Each PR must correspond to exactly one Paperclip issue. Do not combine unrelated changes in a single PR. If you discover adjacent work while implementing a ticket, create a separate issue and PR for it. Exception: closely related issues (e.g., parent/child tasks or tightly coupled changes) may share a single workspace and PR when splitting would be impractical.

Before pushing, run git log --oneline origin/main..HEAD and confirm every commit relates to the single ticket in the branch name. If unrelated commits are present, split them into a separate branch and PR.

Status Transition Rules

• You may move issues to: in_progress, in_review, blocked
• You MUST NOT move issues to done — only the Product Owner can move issues to done after verifying the Definition of Done checklist (all checks green, no merge conflicts). The board then merges the PR. If you move a ticket to done, the PO will revert it. After CTO approval, leave the ticket in in_review and let the PO handle the final transition.
• Before moving to in_review, verify: PR exists and is linked, ALL CI checks pass (no exceptions — “infra-only” or “unrelated” failures still count), no merge conflicts, tests exist for new/changed behavior, no secrets committed, summary comment posted on the issue
• Workspace cleaned up: run task builder:cleanup BUILDER_NAME={identifier} after your PR is pushed and before moving to in_review. Confirm no uncommitted changes remain in the worktree.
• If any CI check fails after you’ve moved to in_review, move the ticket to blocked, identify the failing check, and work to fix it or escalate if it’s outside your control

Process Changes

When you identify a process improvement or need to implement an approved process change, use the process-improvement skill. It guides you through:

1. Identifying the correct file to edit (steering rules, AGENTS.md, SDLC, CONTRIBUTING.md)
2. Creating a workspace and making the change
3. Raising a PR against workspace-root (or the relevant repo)
4. Linking the PR back to the Paperclip issue

Do NOT post process changes as Paperclip issue comments or modify issue descriptions to establish new rules. All process changes must be file-based and PR-reviewed.

Ticket Handoff Pattern

When you cannot complete a task and need another engineer’s help:

• Prefer reassigning the existing ticket to the other engineer with a clear comment explaining context and what remains
• Only create subtasks for genuinely parallel, independent work streams that can proceed simultaneously
• Do NOT create a subtask, block yourself on it, and wait — this creates unnecessary overhead