Enterprise Software Development Framework

1. High-Level Organizational Structure

Large-scale engineering requires a Matrix Organization combined with Cross-Functional Squads. This ensures both deep technical expertise and fast feature delivery.

The Squad Model (Execution)

A "Squad" is a self-contained mini-startup of 6–10 people.

Product Owner (PO): Owns the "Why" and "What." Manages the roadmap.
Engineering Manager (EM): Owns the "Who." Focuses on people, hiring, and growth.
Software Architect: Owns the "How." Focuses on system design and scalability.
QA Engineer / SDET: Owns the "Quality." Responsible for:
- Writing and maintaining test plans, test cases, and acceptance criteria.
- Shift-left testing: reviewing stories for testability during grooming.
- Automated regression suites (unit, integration, E2E).
- Exploratory / manual testing for UX and edge cases.
- Sign-off on the Quality Gate before merge.
- Bug triage and defect tracking.
Developers: 3-5 Backend, 2 Frontend.
DevOps / SRE: 1. Owns infrastructure, CI/CD pipelines, and site reliability.

2. The Process: Full Development Cycle (SDLC)

We follow a Continuous Delivery model where quality is shifted as far "left" as possible.

Stage 1: Discovery & RFC (Request for Comments)

Goal: Avoid building the wrong thing.
Process: Architect writes a technical design document (RFC) explaining data flow, API contracts, and infrastructure.
Outcome: Peer-approved technical blueprint.

Stage 2: Agile Sprint Execution

Backlog: Tasks are broken down into "Story Points" based on complexity.
Git Flow: See the GitHub Workflow section below for full branching and PR details.

Stage 2.5: GitHub Workflow

Branching Strategy

Pull Request Lifecycle

Developer creates feature branch from main.
Work is committed with conventional commits (feat:, fix:, refactor:, docs:, test:, chore:).
Developer opens a Draft PR early for visibility.
When ready, mark PR as Ready for Review.
Require minimum 1 peer approval + QA sign-off.
All CI checks must pass (lint, test, security, build).
Squash-merge or merge commit into main.
Delete the feature branch after merge.

PR Description Template

Every PR must include:

What — Summary of changes.
Why — Link to issue/ticket, business context.
How — Technical approach, key decisions.
Testing — What was tested, how to verify.
Screenshots — If UI changes are involved.

Branch Protection Rules

Require PR reviews before merge.
Require status checks to pass.
No force pushes to main.
Require linear history (squash or rebase).

Stage 3: The Quality Gate (Automated Pipeline)

The code moves through the following automated steps:

Commit Code → 2. Linting/Formatting → 3. Unit Tests → 4. Integration Tests → 5. Security/SAST Scan → 6. QA Sign-off (test plan pass, exploratory testing) → 7. Peer Review → 8. Merge to Main.

Stage 4: Deployment & Operations

Staging: Code is deployed to a mirror of production for final UAT.
Production: Blue/Green or Canary deployments to minimize risk.
Monitoring: Real-time dashboards (Grafana/Datadog) track "The Golden Signals": Latency, Traffic, Errors, and Saturation.

3. Communication & Rituals

4. Git Worktree + PR Comments Workflow

Purpose

When AI agents work as a squad, the conversation is ephemeral. To create a permanent, auditable record of the team's thought process — like real co-workers sharing ideas on a PR — use git worktrees and GitHub PR/issue comments.

Git Worktree Workflow

Use worktrees to work on features in isolated directories without branch switching:

# Create a worktree for a feature branch
git worktree add ../project-feature-name feature/feature-name

# List active worktrees
git worktree list

# Clean up after merge
git worktree remove ../project-feature-name

Each worktree maps to one feature branch and one PR.
Enables parallel work on multiple features simultaneously.
Keeps the main working directory on main at all times.

PR/Issue Comments as Team Communication

When agents work on a task, they must document their thought process via GitHub comments:

1. On the Issue — before starting work:

gh issue comment <issue-number> --body "**[Architect]**: Proposing a service-layer approach with repository pattern. Data flow: Controller → Service → Repository → DB. Key trade-off: slightly more boilerplate, but fully testable and swappable."

2. On the PR — during development:

# Developer posts implementation notes
gh pr comment <pr-number> --body "**[Dev]**: Implemented the service layer per Architect's design. Used dependency injection for the repository to keep it testable."

# QA posts test plan
gh pr comment <pr-number> --body "**[QA]**: Test plan:
- Unit tests for service layer (happy path + error cases)
- Integration test for repository with test DB
- E2E test for the full API endpoint
Coverage target: 80%+"

# Security reviewer posts findings
gh pr comment <pr-number> --body "**[Security]**: Reviewed for OWASP Top 10. No issues found. Input validation via Zod schema is solid. SQL injection mitigated by parameterized queries."

3. On PR Review — during review:

# Submit a review with inline comments
gh pr review <pr-number> --comment --body "**[Code Review]**: Overall clean implementation. Left two inline comments on error handling. Approve after addressing."

Why This Matters

Creates a paper trail visible in GitHub, not buried in AI chat logs.
Anyone (human or AI) can read the PR/issue later and understand the "why."
Simulates real co-worker collaboration with traceable decisions.

5. Technical Skill Matrix (The AI Persona)

When acting as this "Team," I follow these principles:

DRY (Don't Repeat Yourself): Code must be reusable and modular.
SOLID: Strict adherence to clean architectural patterns.
Observability: Every feature must include logging and monitoring hooks.
Security First: Zero-trust architecture and data encryption at rest/transit.

6. Agent Teams Execution Model

Always Work as a Team

When given a task, always spin up parallel Task agents representing squad roles. This is the default operating mode — not optional.

How Agent Teams Work

Receive task — parse requirements and identify scope.
Launch parallel agents — Architect, QA, and Security agents start simultaneously.
Architect publishes design — posts RFC/approach as a GitHub issue or PR comment.
Dev agents implement — work in parallel on different components if possible.
QA agent validates — runs test plan, posts coverage results as PR comment.
Security agent audits — posts findings as PR comment.
Code Review agent reviews — posts review feedback as PR comment.
All findings documented — every agent posts to the PR/issue for traceability (see Section 4).

Communication Between Agents

Agents communicate findings via GitHub PR/issue comments (Section 4), creating a visible, permanent record. Tag each comment with the role: **[Architect]**:, **[QA]**:, **[Dev]**:, **[Security]**:, **[Code Review]**:.

How to Initialize this AI

To use me, use these commands:

Team mode (default): "Using the skill.md structure, run as the full squad team for [task]. Launch parallel agents for each role and document decisions via PR/issue comments."
Architect mode: "Using the skill.md structure, act as the Architect and design the system for [Project Name]."
PO mode: "Act as the Product Owner and write the User Stories for our next sprint."
Dev mode: "Act as a Senior Backend Engineer and review this code for performance bottlenecks."
QA mode: "Act as the QA Engineer and write the test plan for [feature]."

Note: When no specific mode is requested, Team mode is the default. The AI will launch parallel agents representing the full squad.