diff --git a/docs/ai-software-factory-briefing.html b/docs/ai-software-factory-briefing.html new file mode 100644 index 0000000..954d426 --- /dev/null +++ b/docs/ai-software-factory-briefing.html @@ -0,0 +1,903 @@ + + + + + + AI Software Factory — Advisor Briefing + + + +
+ + +
+
Advisor Briefing · Emergence AI
+

AI Software Factory

+

+ An autonomous engineering operating system that converts Jira issues into tested, + reviewed pull requests across multiple repositories — with a single command. +

+
+
Core skills: built & tested
+
Orchestrator: implemented
+
Cloud deployment: remaining
+
+
+ + +
+

The Vision

+
+
+ "Encode the entire software delivery lifecycle as composable Claude Code skills, + then orchestrate them autonomously across repositories — so a 4-person team + can ship at the pace of 40, with 80 % of actions requiring zero human input." +
+
+
+
+
80/20
+
Autonomy model — 80 % auto, 20 % strategic checkpoints
+
+
+
~85 %
+
Average autonomy across all skills
+
+
+
40 → 3
+
Manual prompts replaced by strategic checkpoints per issue
+
+
+
+
Sprint throughput vs sequential delivery (8 parallel agents)
+
+
+
24
+
Composable skills covering the full SDLC
+
+
+
5 repos
+
Actively wired: runtime, runtime-ui, talk2data, data-readiness, semi
+
+
+
+ + +
+

End-to-End Autonomous Pipeline

+

+ A single command (/autonomous-implement ABI-123) runs the full SDLC without human + intervention until the plan-approval and PR-review checkpoints. +

+
+
Jira Issue
+
+
Fetch & branch
+
+
Research codebase
+
+
Create plan ✋
+
+
Generate evals
+
+
Implement
+
+
Run evals (3× retry)
+
+
Create PR ✋
+
+
9-agent code review
+
+
Update Jira
+
+

✋ = strategic human checkpoint  ·  Everything else is autonomous  ·  Typical time: 3–8 min / issue

+
+ + +
+

What Has Been Built

+ +

Autonomous end-to-end skills

+
+
+ AUTO +
+
/autonomous-implement
+
Full SDLC for a single Jira issue. Accepts --context-file for orchestrator-injected knowledge.
+
+
+
+ AUTO +
+
/autonomous-sprint
+
Parallel multi-issue sprint. Up to 8 concurrent agents in isolated git worktrees — 8× throughput.
+
+
+
+ +

Core development skills

+
+
+ GUIDED +
+
/create-plan
+
Interactive planning from a Jira ticket. Parallel research agents, section-by-section approval, saved to specs/.
+
+
+
+ GUIDED +
+
/implement-plan
+
Phased implementation of an approved plan. Human verification pause between phases.
+
+
+
+ AUTO +
+
/eval-generator
+
Converts Jira acceptance criteria into pytest suites: functional, performance, quality, edge-case.
+
+
+
+ AUTO +
+
/code-review
+
9 parallel specialist agents (security, perf, test quality…) synthesised by a senior reviewer agent.
+
+
+
+ GUIDED +
+
/create-pr
+
GitHub PR with size check (flags if >300 lines / 10 files), labels, comprehensive description.
+
+
+
+ GUIDED +
+
/commit
+
Groups changes into logical atomic commits with conventional messages. Never uses git add -A.
+
+
+
+ +

Research, quality & Jira skills

+
+
+ AUTO +
+
/research-codebase
+
Parallel sub-agents document architecture, patterns, dependencies. Output saved to specs/research/.
+
+
+
+ AUTO +
+
/jira-to-branches
+
JQL query → standardised branches per issue type. Updates Jira with branch links.
+
+
+
+ AUTO +
+
/jira-update
+
Posts PR links, eval results, implementation notes, and status transitions back to Jira.
+
+
+
+ AUTO +
+
/validate-plan
+
Checks implementation against plan, ADRs, and architecture docs. Produces red/yellow/green report.
+
+
+
+ AUTO +
+
/create-e2e-testplan
+
Parallel frontend, backend, integration agents → structured test plan in specs/testing/.
+
+
+
+ AUTO +
+
/update-e2e-testplan
+
Diffs two releases, marks [NEW]/[UPDATED]/[DEPRECATED] tests accordingly.
+
+
+
+ +

Issue management & utility skills

+
+
+ GUIDED +
+
/create-bug
+
Interactive Jira bug creation with regression analysis from recent commits.
+
+
+
+ AUTO +
+
/create-bug-from-video
+
Analyses screen recordings (ffmpeg + Whisper), identifies bug, files in Jira with video attached.
+
+
+
+ GUIDED +
+
/create-epic
+
Creates Jira epics from a standard template or batch CSV/Excel input.
+
+
+
+ AUTO +
+
/describe-pr
+
Generates and updates GitHub PR descriptions by fetching diff + related docs.
+
+
+
+ GUIDED +
+
/split-pr
+
Splits large feature branches into focused PRs with dependency documentation.
+
+
+
+ GUIDED +
+
/generate-migration
+
Database migration files (Alembic, Django, Knex, Prisma…). Previews SQL before applying.
+
+
+
+ AUTO +
+
/dogfood
+
Browser-driven QA. Reproduces bugs with video evidence, files 5–10 Jira issues per session.
+
+
+
+
+ + +
+

Orchestrator Layer

+

+ A thin Python workspace layer (~500 lines) that injects repository knowledge and routes issues to the + correct repository before handing off to the Claude Code skills. It does not reimplement the SDLC. +

+
+
+

Router

+

Three-strategy routing: Jira component field → keyword analysis of description → repo: label prefix. Falls back to runtime.

+
+
+

KnowledgeEngine

+

Loads per-repo knowledge (architecture, patterns, conventions, dependencies) and Foundations standards into a single context file injected as --context-file.

+
+
+

Executor

+

Creates a temp knowledge context file, invokes /autonomous-implement via subprocess or Skill tool. Handles single-repo and multi-repo flows.

+
+
+

Planner

+

Produces a TaskGraph with per-repo tasks and inter-repo dependencies. Step sequences vary by issue type (Story / Bug / Task).

+
+
+
+

CLI usage

+ + + + + + + + + +
CommandWhat it does
python -m orchestrator implement ABI-123Auto-route and implement one issue
python -m orchestrator implement ABI-123 --repo runtimeOverride routing to a specific repo
python -m orchestrator multi-repo SDK-456 --repos sdk,runtime,runtime-uiCross-repo implementation with dependency ordering
python -m orchestrator sprint --jql "filter=17150"Full parallel sprint from a Jira filter
python -m orchestrator knowledge --repo runtime --listInspect loaded knowledge for a repo
+
+
+ + +
+

Knowledge System

+
+
+

Repository knowledge

+

+ Each of the 5 active repositories has a knowledge/repositories/<name>/ + directory containing four Markdown files extracted from the repo's own docs: +

+
+ + + + + + + +
architecture.mdComponent map, data flows, ADR index
patterns.mdCoding patterns and idioms
conventions.mdNaming, structure, style rules
dependencies.mdKey libs, versions, constraints
+
+
+
+

Foundations standards

+

+ Platform-wide standards extracted from em-foundations and applied to every issue: +

+
+

Definition of Done (9 items)

+

Functionality · ≥80 % test coverage · Code review · Pacto contracts · Configuration · Observability · Documentation · Security · Deploy readiness

+
+
+

Hard constraints

+

Air-gapped (no cloud APIs in app code) · Vault for secrets · cosign image signing + SBOM · ArgoCD deploy pipeline · British English docs

+
+
+
+
+ + +
+

Repository Wiring

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RepositoryJira ComponentStackAdapter
em-runtimeRuntime · Connectors · SDKPython / Poetry / pytestruntime.py done
em-runtime-uiUITypeScript / pnpm / vitestin progress
em-talk2dataTalk2DataPython / Poetry / pytestin progress
em-data-readinessData ReadinessPython / Poetry / pytestin progress
em-semiSemiPython / Docker / pytestsemi.py done
+
+ + +
+

Completion Tracker

+
+
+ +
+
24 SDLC skills authored and validated
+
Full coverage: issue intake, planning, evals, implementation, review, PR, Jira update, QA browser testing, epic/bug creation, migration generation.
+
+
+
+ +
+
80/20 autonomous-mode settings
+
Auto-approves safe read/write/git/docker operations; blocks destructive commands; defines 3 strategic human checkpoints per issue.
+
+
+
+ +
+
MCP Atlassian integration
+
Jira issue fetch, search (JQL), comment, create, transition, and Confluence page fetch all wired via mcp-atlassian server.
+
+
+
+ +
+
Orchestrator Python layer
+
Router, KnowledgeEngine, Executor, Planner, CLI, knowledge sync scripts — all implemented.
+
+
+
+ +
+
Knowledge corpus for all 5 repos + Foundations
+
Architecture, patterns, conventions, dependencies extracted and in knowledge/. Auto-sync script watches git hash of source docs.
+
+
+
+ +
+
Workflow engine for parallel sprints
+
autonomous-sprint.js — three-phase Setup / Audit / Implement with isolated git worktrees per agent. Up to 8 concurrent.
+
+
+
+ +
+
Prompt templates for specialist agents
+
Architect, Planner, Backend, UI, Evaluator, Reviewer — parameterised Markdown templates used by the orchestrator Planner.
+
+
+
+ +
+
Repository adapters (runtime + semi)
+
Abstract RepositoryAdapter base with concrete implementations covering build, test, lint, format, branch, architecture, patterns.
+
+
+
+ +
+
Packaged as a Claude Code plugin
+
Installable via /plugin install em-software-factory@em-plugins. Plugin manifest declares all skills, hooks, and MCP config.
+
+
+
+ +
+
Security & secret controls
+
gitleaks scan script, settings block env file writes, MCP env vars loaded from shell (never committed).
+
+
+
+
+ + +
+

What Remains: Cloud Deployment

+
+

The one open chapter — running agents and the harness in cloud

+

+ Everything described above runs locally inside Claude Code (desktop or CLI). + The next step is lifting the harness and agents into a persistent cloud environment so the factory + can run unattended, scale horizontally, and integrate with the team's CI/CD pipeline. +

+
    +
  • +
    +
    Managed Agent hosting — deploy skills as server-hosted Claude Managed Agents so they run without a developer's laptop
    +
    Anthropic's Managed Agents API provides a hosted sandbox with persistent context and tool access
    +
    +
  • +
  • +
    +
    Orchestrator service — wrap the Python orchestrator as a long-running service (container / Lambda / Cloud Run)
    +
    Needs: Jira webhook trigger → route → invoke skill → report result, all without a human in the loop
    +
    +
  • +
  • +
    +
    Secure credential delivery — Jira/GitHub tokens, MCP config, and repo SSH keys in cloud-native secret store (Vault / AWS Secrets Manager)
    +
    Currently loaded from developer shell env vars; needs K8s-style injection for headless runs
    +
    +
  • +
  • +
    +
    Repo access & worktree storage — agents need authenticated git clone and writable ephemeral workspace per task
    +
    Options: ephemeral containers per agent, shared PVC with worktree isolation, or GitHub Codespaces-style environments
    +
    +
  • +
  • +
    +
    Observability & reporting — structured logs per sprint, per agent, per issue; reporter module surfaces success/partial/failed counts
    +
    Reporter module exists in orchestrator but needs a sink (Datadog, Grafana, or Jira comment)
    +
    +
  • +
  • +
    +
    Air-gapped packaging — for semiconductor customers who cannot call external APIs
    +
    The Foundations ADRs already mandate air-gapped operation; the factory itself must be deployable without internet access
    +
    +
  • +
+
+
+ + +
+

Technology Stack

+
+
+

AI / Orchestration layer

+ Claude Code v2.1.81+ + Claude Sonnet (skills) + Anthropic Workflow engine + MCP (Model Context Protocol) + mcp-atlassian + agent-browser +
+
+

Orchestrator & tooling

+ Python 3.8+ + argparse CLI + subprocess + Skill tool + ffmpeg + Whisper (STT) + gitleaks +
+
+

Integrations

+ Jira (MCP) + Confluence (MCP) + GitHub (gh CLI) + ArgoCD + Dagger + Vault (secrets) +
+
+

Repo quality toolchain

+ pytest + 80 % coverage + ruff + black + mypy + eslint + prettier + tsc + Pacto (contract tests) + cosign + SBOM +
+
+
+ + + +
+ +