SDLC for Agent-Led Feature Building

1. Strategy Discussions

Owner: CEO (with board input)

Features start as board-created issues or CEO-initiated proposals on Paperclip.
Strategic alignment is validated against the company goal before any work begins.
For significant features, the CEO creates a plan document on the issue covering scope, success criteria, and trade-offs.
Board reviews and comments on the plan. CEO iterates until the board approves.
Small changes (bug fixes, minor improvements) skip this phase and go straight to backlog.

2. Artefact Storage

Home directory: /workspace/.ai/projects/cascadeguard/

All project artefacts live in the filesystem under this root. Paperclip issues link to the relevant files — the source of truth is the file, not the issue body.

Artefact	Location	Format
PRDs / feature specs	`/workspace/.ai/projects/cascadeguard/prds/<name>.md`	Markdown
ADRs (Architecture Decision Records)	`/workspace/.ai/projects/cascadeguard/adr/NNN-title.md`	Markdown (MADR template)
Strategy docs	`/workspace/.ai/projects/cascadeguard/strategy/<name>.md`	Markdown
Technical designs	`/workspace/.ai/projects/cascadeguard/designs/<name>.md`	Markdown
Designer briefs	`/workspace/.ai/projects/cascadeguard/designer-briefs/<name>.md`	Markdown
Plans	`/workspace/.ai/projects/cascadeguard/plans/<name>.md`	Markdown
API specs	`docs/api/` in source repo	OpenAPI YAML
This SDLC document	`/workspace/.ai/projects/cascadeguard/sdlc.md`	Markdown

Source code lives in /workspace/repos/ (or in a builder workspace when applicable).

Rules:

Artefacts live in the project folder. Paperclip issues reference them by path.
PRs should be raised when artefacts are created or updated so they can be reviewed and merged.
Each agent should have a workspace using the builder pattern and workspace management skill; tickets should have a workspace when needed.
ADRs are immutable once accepted. New decisions supersede old ones.
Paperclip issue documents (plan, etc.) can serve as lightweight pointers or summaries linking to the canonical file.

3. Feature Conversations

All feature discussion happens in Paperclip issue comments. This keeps context co-located with the work.
Use @-mentions sparingly (they trigger heartbeats and cost budget).
For cross-team input, the CEO tags the relevant agent in a comment with a clear ask.
Board members comment directly on issues when they have input.
Conversations should converge on a decision. CEO or CTO posts a “Decision:” comment to close the discussion.

4. What Belongs in Paperclip

Paperclip is for actionable work, not observability data.

Only create a Paperclip issue when an agent can take a concrete action to resolve it. Raw findings, scan results, and status reports do NOT belong in Paperclip.

Belongs in Paperclip	Does NOT belong in Paperclip
Feature implementation	CVE scan results (use GitHub issues/advisories)
Bug fix (with clear repro)	Dependabot alerts (stay in GitHub)
Infrastructure task	Informational vulnerability reports
Tech debt remediation	Daily digest summaries (post as comments on existing issues)
Board-approved work items	Findings with no clear remediation path

Where non-Paperclip items go:

CVE/vulnerability findings → GitHub Security Advisories or per-CVE GitHub issues on the affected repo
Dependabot alerts → Stay in GitHub; tracked in daily digest
Scan reports → GitHub Actions artifacts + summary in daily digest
Monitoring alerts → Pushover notifications; only escalate to Paperclip if agent action is needed

Escalation to Paperclip: A finding graduates to a Paperclip ticket only when:

It requires agent work (code change, config update, investigation), AND
Board has approved the work (via triage digest approval flow)

5. When a Ticket Goes Into Backlog

A ticket enters backlog when:

It has a clear title and description (what, not how).
It is linked to a goal (goalId set).
It has a priority assigned (critical / high / medium / low).
It has delivery layers identified (see below).
It does NOT yet have board approval to start.

End-to-End Layer Identification (Required)

Every ticket MUST identify which delivery layers it touches at creation time, not at review. This prevents scope gaps where backend work ships without corresponding frontend changes (or vice versa).

Layers: backend | frontend | api | infra | docs

The ticket description must include a Layers line listing all affected layers. Example:

**Layers:** backend, api, frontend

Rules:

If a ticket touches >1 layer, the description must explain the scope for each layer.
If a multi-layer ticket is assigned to a single IC, all layers must be delivered in the same PR or a clear follow-up plan must exist before in_review.
CTO/PO triage checks verify layer identification is present and correct before approving to todo.
Missing layer identification blocks the ticket from moving to todo.

Who creates backlog tickets:

Board — creates directly.
CEO — creates based on strategy.
CTO — creates based on technical needs (tech debt, infra).
Any agent — proposes via comment on a parent issue; CEO or CTO creates the ticket.

6. When a Ticket Is Ready to Build

A ticket moves from backlog to todo only after board approval.

Approval gate:

The ticket must have a clear description and acceptance criteria.
For non-trivial features: a PRD or design doc must exist in /workspace/.ai/projects/cascadeguard/prds/ or designs/.
Board member manually moves the ticket to todo (or comments “approved to start”).
Engineers pull from the prioritised todo list (see §13 Work Assignment).

What “ready” means:

Description answers: what are we building, why, and what does done look like?
Delivery layers are identified and the scope for each layer is described.
Dependencies are identified and unblocked.
If it touches >1 layer, the ticket either covers all layers or child tickets exist for each.
If it touches architecture, an ADR exists or is part of the ticket scope.

7. Pull Request Process

Branch strategy: Feature branches off main. One branch per ticket.

PR creation:

Agent creates a branch named <identifier>/<short-description> (e.g., CAS-45/add-billing-endpoint).
Agent commits with descriptive messages. Every commit includes Co-Authored-By: Paperclip <noreply@paperclip.ing>.
Agent opens a PR via gh pr create with:
- Title: ticket identifier + short description.
- Body: Summary, test plan, link to Paperclip issue.
Agent updates the Paperclip issue with PR link and sets status to in_review.

Review process:

Automated checks run first: lint, type check, unit tests, integration tests, security scan.
CTO reviews all PRs for architecture and code quality.
Board reviews PRs for significant features (CEO flags which ones need board review).
Reviewer comments on the PR. Agent addresses feedback in new commits (no force-push).
Once approved, CTO or board merges to main. Agents do not merge their own PRs.

PR rules:

No direct commits to main.
PRs must pass all CI checks before review.
Squash merge preferred for clean history.
Delete branch after merge.

8. Testing Pyramid

         /  E2E  \          <- Few, slow, high confidence
        / Integration \      <- Moderate, test boundaries
       /   Unit Tests   \    <- Many, fast, isolated
      / Static Analysis   \  <- Lint, type check, security

Layer details:

Layer	What	Tools	Coverage target
Static analysis	Linting, type checking, secret scanning	ruff/eslint, mypy/tsc, gitleaks	100% of code
Unit tests	Pure functions, business logic, utilities	pytest / vitest	80%+ line coverage
Integration tests	API endpoints, DB queries, service boundaries	pytest + real DB, httpx	Key paths covered
E2E tests	Critical user flows, deployment smoke tests	Playwright or API-level flows	Top 5 user journeys

Agent responsibilities:

Every PR must include tests for new/changed behavior.
Agent runs tests locally before opening PR.
CI runs the full pyramid on every PR.
Test failures block merge. No exceptions.

9. Definition of Done

A ticket is done when ALL of the following are true:

Code is merged to main.
All tests pass in CI (unit, integration, E2E as applicable).
No new lint warnings or type errors introduced.
PR was reviewed and approved by CTO (and board if flagged).
Documentation updated if user-facing behavior changed.
ADR written if an architectural decision was made.
Paperclip issue status set to done with a closing comment.
All identified delivery layers are addressed (no partial-layer delivery).
No known regressions in existing functionality.

10. Data Classification and Repo Security

Rule: Sensitive data and company-internal artefacts MUST NOT be committed to public repositories.

Data type	Where it lives	Public repo?
Strategy docs, PRDs, ADRs, designs, SDLC	`/workspace/.ai/projects/cascadeguard/` (workspace-root repo)	NO
Source code (open-source)	Public repo (e.g. `cascadeguard/cascadeguard`)	YES
API specs (public)	`docs/api/` in source repo	YES
Agent conventions (`CLAUDE.md`)	Source repo root	YES (references paths only, no sensitive content)
Secrets, keys, credentials	Never committed anywhere	NO
Internal business data, customer data	Never committed anywhere	NO

Enforcement:

Public repos MUST have .ai/ in .gitignore.
Agents MUST check what repo they are committing to before pushing. If it is public, only source code, tests, CI config, and public docs are allowed.
If sensitive data is accidentally committed to a public repo, treat it as a security incident: scrub from history immediately, rotate any exposed secrets, and notify the board.

11. Additional Processes

Hotfix Process

Critical production bugs skip the backlog queue.
Board or CEO creates a critical priority ticket — immediate todo.
Same PR and review process applies, but review is expedited.

Tech Debt

CTO maintains a running list of tech debt issues.
CEO allocates ~20% of capacity to tech debt per cycle.
Tech debt tickets follow the same approval flow.

Deployment

Merges to main trigger automated deployment to staging.
Production deploys require explicit board approval (for now).
Rollback plan documented before any production deploy.

Retrospectives

After each significant feature ships, CEO posts a brief retro comment on the parent issue: what went well, what didn’t, what to change.
Learnings feed back into this SDLC (living document).

12. Lifecycle Summary

Idea -> Strategy Discussion -> Backlog (with goal + priority)
  -> Board Approval -> Todo (assigned to agent)
  -> In Progress (checked out, branch created)
  -> In Review (PR open, CI green, CTO review)
  -> Done (merged, deployed to staging, issue closed)

Every transition is visible in Paperclip. No work happens without a ticket. No code ships without a review.

13. Work Assignment — Pull Model

Engineers pull work from the prioritised backlog rather than receiving assignments from the CTO. This prevents over-assignment and gives engineers ownership of their capacity.

How it works:

CTO and PO maintain backlog priority. Issues in todo are ordered by priority. The CTO ensures technical context and scope are clear before an issue is ready for pickup.
Engineers pull when they have capacity. When an engineer finishes work or has fewer than 3 active issues (todo + in_progress), they pick the highest-priority unassigned todo item that matches their skills.
WIP limit: max 3 active issues per engineer. Engineers must not pull new work if they already have 3 active issues.
No duplicate tasks. If an existing task covers the work, reopen/unblock it instead of creating a new one.
Blocked task hygiene. When a task is blocked, either unblock it or escalate within 1 heartbeat. Do not leave blocked tasks accumulating.

CTO may still assign directly when:

A critical/urgent issue needs a specific engineer’s expertise
An engineer is idle and hasn’t pulled work (escalation path)
Cross-team coordination requires explicit routing

Techcle Wiki

Explorer

Sdlc