Skip to content

SOP-DEV-implementation-workflow-v1.0

1. Purpose

Define the standard execution pattern for code.platform and CDO team agents when implementing a feature or bug fix — from Task Brief receipt through QA signoff. Ensures consistent quality, auditability, and no surprises at review.

2. Implementation Phases

Brief → Clarify → Branch → Implement → Self-test → QA handoff → Signoff → Merge → Close

No phase is skippable. Compressed timelines shorten each phase; they do not eliminate phases.

3. Phase Runbook

Phase 1 — Brief receipt and clarification

  1. Read the Task Brief fully before touching any code
  2. If any Done Criterion is ambiguous: ask before implementing (per "ask before assuming" principle in agent contracts)
  3. Identify dependencies: upstream APIs, data sources, agent contracts that reference this component
  4. Identify the security review gate: if this touches credentials, authentication, new external endpoints — security.ops review required before Phase 3

Phase 2 — Branch

  1. Create a feature branch from main: feat/{slug} or fix/{slug} for bugs
  2. Confirm branch protection rules are active on main (per SOP-OPS-github-branch-protection-v1.0) — no direct pushes to main
  3. Update Monday.com item status to "Working on it"

Phase 3 — Implement

Implementation standards (non-negotiable):

Standard Requirement
No plaintext credentials All secrets via op read or op run — never hardcoded
No silent failures Errors logged or surfaced — no swallowed exceptions in integration code
Atomic commits Each commit does one thing; message is imperative present tense ("Add webhook validation")
No scope creep If you discover adjacent work while implementing, file it as a new feature request, don't fold it in
Ask before architecture changes If implementation reveals the architecture needs to change, stop and surface to CDO before proceeding

At minimum one Status Report (CLAUDE.md Section 6B) filed per implementation session, including: files touched, commands run, what's complete, what's pending.

Phase 4 — Self-test

Before handing off to QA:

  1. Run the feature against its Done Criteria directly — does each criterion pass?
  2. Run a regression check on adjacent functionality — did anything nearby break?
  3. Check for hardcoded credentials: run grep patterns per SOP-OPS-credential-management-v1.0 Section 6 against changed files
  4. Confirm Monday.com status updated and Status Report current

For integrations: run a live smoke test against the actual API/service (not just a mock).

Phase 5 — QA handoff

  1. Open a PR to main with a description including:
  2. What this implements and why
  3. Done Criteria and whether each passes (with evidence)
  4. Files changed
  5. How to test
  6. Known limitations or deferred work
  7. Notify qa.testing (or the appropriate QA specialist) via session-dir drop + #agent-handoffs: "PR ready for review — {PR link or description}"
  8. Do not merge before QA signoff

Phase 6 — QA signoff

qa.testing (or assigned QA specialist) runs SOP-DEV-qa-signoff-v1.0. If confidence is MEDIUM or HIGH and no criterion fails: approves the PR.

If defects found: sent back to Phase 3. Document the defect loop in the QA Report.

Phase 7 — Merge and close

  1. Squash-merge to main (per branch protection standard)
  2. Delete the feature branch
  3. Update Monday.com item to Done with a completion note (what was delivered, PR reference)
  4. If this implementation changed an agent's capabilities: CDO notifies the agent via session-dir drop + #agent-handoffs
  5. If a new SOP was needed as part of this implementation: route to sop.manager

4. Status Reporting

For implementations running >1 session, code.platform files a Status Report (CLAUDE.md Section 6B) at each session end including: - Files touched - Commands run - Tests run and results - Lint results (if applicable) - Rollback note (can the previous state be restored if this is reverted?) - Branch/commit reference

5. Rollback Procedure

If a merge to main breaks something:

  1. git revert {commit} — do not force-push
  2. File a SEV2 Bug Report per SOP-DEV-bug-triage-v1.0
  3. Notify CDO and chief.staff via #agent-handoffs
  4. Root cause documented before re-implementation

Change Log

Version Date Change
v1.0 2026-04-21 Initial draft — sop.manager.

Owner: code.platform Executive sponsor: cdo Drafted by: sop.manager Status: Draft — pending CDO review + approval Version: v1.0