Concilium/PROJECT_PROPOSAL.md

PROJECT_PROPOSAL.md

Concilium

Project Proposal and High-Level Requirements

1. Overview

Concilium is a master-agent orchestration platform for multi-repository software delivery.

It is designed to help a single engineer, and later teams, coordinate complex software systems that span multiple repositories by introducing a persistent master project abstraction. A master project represents one logical software system made up of multiple codebases, infrastructure definitions, documentation, pipelines, and related delivery assets.

Examples of a master project might include:

• website-frontend
• website-backend
• website-cd
• website-shared
• website-docs
• website-infra

Concilium should create and manage:

• a master agent that understands the overall project goals, milestones, architecture, dependencies, and state of delivery
• a repo agent for each repository that deeply understands its assigned codebase
• optional specialist agents for architecture, QA, documentation, CI/CD, release readiness, and issue management

Concilium is planner/coordinator first. It is not primarily a coding assistant. Its main purpose is to help plan, coordinate, track, and drive multi-repo initiatives to successful completion using persistent project knowledge, issue-tracker-backed workflows, and durable orchestration.

---

2. Vision

Build a durable software delivery control plane that can reason across repositories, architecture, issues, CI/CD, and agent execution to coordinate real project work from concept through integration readiness.

Concilium should become the operating system for a software initiative that spans more than one repo and more than one active line of work.

---

3. Product Thesis

Concilium exists to solve a problem that current repo-local coding agents do not fully solve:

A software system is rarely just one repo. Real delivery requires coordination across:

• multiple codebases
• infrastructure
• issue trackers
• branching strategies
• validation pipelines
• architecture constraints
• rollout sequencing
• human approvals
• cross-repo dependencies

Concilium should act as the coordinating intelligence for this environment.

Its core value is:

• understanding the full project
• maintaining persistent context
• decomposing initiatives into properly tracked work
• delegating work to repo-local and specialist agents
• coordinating dependencies and feedback loops
• helping drive the system toward a complete and working result

---

4. Initial User Profile

Initial target user:

• a single engineer / technical lead / founder / CTO-style operator

This user likely:

• owns several repos
• works across architecture, implementation, and delivery
• wants more than a code copilot
• needs continuity across machines and sessions
• wants strong SDLC traceability
• wants a reusable control plane for ongoing work

The initial UX and implementation should optimize for a single powerful operator while keeping the design extensible for future multi-user support.

---

5. Core Concepts

5.1 Concilium

The overall platform, product, and orchestration system.

5.2 Master Project

A first-class object representing one logical software system made up of multiple repositories and related workstreams.

A Master Project should own:

• project identity
• goals and outcomes
• milestones
• architecture model
• repo relationships
• work decomposition
• status and readiness

5.3 Master Agent

The persistent coordinating LLM identity for a Master Project.

The Master Agent should understand:

• project goals
• desired outcomes
• architecture
• dependencies across repos
• current work status
• blockers and risks
• rollout/integration progress

5.4 Repo Agent

A persistent repo-specific LLM identity.

Each Repo Agent should deeply understand:

• its repository structure
• code conventions
• modules and components
• build/test/deploy behavior
• local architecture
• repo-local branching and workflow norms

5.5 Specialist Agents

Optional agent types used for focused functions, such as:

• architecture agent
• QA/test agent
• documentation agent
• CI/CD agent
• release agent
• issue/project management agent

---

6. Guiding Principles

6.1 Planner and Coordinator First

Concilium should primarily orchestrate, plan, route, track, and reconcile work. It is not a chat wrapper around coding models.

6.2 Master Project as the Coordination Center

The Master Project should be the main conceptual container for goals, architecture, issue relationships, and delivery progress.

6.3 Tracker-Native Work

All actionable work must be represented through Jira or GitHub Issues. Concilium may hold internal metadata, but not a hidden shadow backlog that replaces the official work tracker.

6.4 Persistent, Cross-Machine Memory

Knowledge and state must survive across sessions, machines, and environments.

6.5 Human Governance

Concilium should be highly editable and governable by a human operator. The human remains in charge.

6.6 Architecture as a First-Class Artifact

Architecture must be modeled, stored, versioned, editable, and used in reasoning.

6.7 Multi-Agent by Design

The system must assume many cooperating agents, not one massive prompt loop.

6.8 Production-Minded Foundation

The project should be designed as a durable product foundation, not a throwaway prototype.

---

7. Problem Statement

Existing AI coding tools are increasingly strong at local implementation within a repo, but software delivery often fails at the coordination layer:

• work is not broken down well
• cross-repo changes are poorly synchronized
• architecture intent drifts from implementation reality
• issue trackers are incomplete or stale
• CI/CD outcomes are disconnected from planning
• decisions are lost across sessions and machines
• humans become the fragile integration layer

Concilium should reduce this gap by acting as the durable orchestration layer for software delivery.

---

8. Goals

8.1 Primary Goals

Concilium v1 should allow a user to:

• create a Master Project
• attach multiple repos
• establish persistent knowledge for project and repos
• define/edit a project architecture model
• use Jira or GitHub Issues for all work creation and coordination
• decompose work across repos
• delegate planned work to repo agents
• coordinate validation, dependencies, and progress
• persist and resume orchestration across sessions and machines

8.2 Longer-Term Goals

Future versions should expand toward:

• stronger automation
• richer specialist agents
• deeper CI/CD orchestration
• release coordination
• multi-user and team support
• broader platform integrations
• more autonomous, policy-controlled execution

---

9. Non-Goals for Initial Phase

Initial development should not overreach into all possible future features.

Likely non-goals for the first phase:

• full autonomous deployment to production
• large-scale team collaboration features
• full enterprise RBAC model
• marketplace/plugin ecosystem
• broad provider support beyond practical first integrations
• complete replacement of existing PM tools
• exhaustive self-healing agent autonomy

These may come later, but should not distract from establishing a strong core.

---

10. High-Level Functional Requirements

10.1 Master Project Management

Concilium must support:

• creating a Master Project
• naming and describing it
• defining goals, outcomes, milestones, and status
• attaching multiple repositories
• storing shared context across repos
• maintaining master-level summaries and memory
• surfacing master-level status and risks

A Master Project should serve as the umbrella object for coordinated software delivery.

---

10.2 Repository Registration and Ownership

Concilium must support:

• registering repos to a Master Project
• associating metadata to repos
• defining repo role or purpose within the larger project
• cloning, syncing, and updating repo state
• linking repos to issue tracker and CI/CD metadata
• tracking repo branch and PR history

Each repo must be a durable, queryable object in the platform.

---

10.3 Repo Agent Capabilities

Each repo should have a persistent Repo Agent identity.

Repo Agents must be able to:

• deeply understand their codebase
• maintain long-term repo-specific memory
• generate local plans for assigned work
• reason about local architecture and conventions
• understand build/test/deploy patterns
• collaborate with specialist agents when needed
• report progress, blockers, and validation results back to the Master Agent
• align work to Jira or GitHub Issues

Repo Agents should be persistent identities even if runtime processes are launched on demand.

---

10.4 Master Agent Capabilities

The Master Agent must be able to:

• understand overall project goals and milestones
• understand the architecture model
• understand relationships between repos
• break initiatives into issue-backed work
• assign and route work to repo agents and specialists
• reason about dependencies, sequencing, and blockers
• gather and reconcile outputs from multiple agents
• track progress toward system-level success
• reason about integration readiness and remaining gaps

The Master Agent is the project-level coordinating intelligence.

---

10.5 Specialist Agents

Concilium should support specialist agent roles, including but not limited to:

• Architecture
• QA/Test
• Documentation
• CI/CD
• Release/Integration
• Issue/PM

These should be modeled as pluggable agent capabilities rather than hard-coded one-off workflows.

---

10.6 Issue-Tracker-Native Tasking

Concilium must use Jira or GitHub Issues for 100% of task creation and coordination.

This requirement is mandatory.

Implications:

• every initiative must map to issues
• every decomposed task must exist as an issue, subtask, linked issue, epic, or equivalent construct
• all meaningful work must be traceable through the tracker
• branches, PRs, validations, and deliverables must map back to issue-tracked work
• Concilium may enrich tracker records with metadata, but not replace them

Concilium must treat issue tracking as part of the delivery contract, not as an optional integration.

---

10.7 Planning and Decomposition

Concilium must support:

• intake of a new initiative
• project-level planning
• decomposition into repo-scoped work
• decomposition into specialist-agent work
• dependency mapping
• sequencing
• acceptance criteria definition
• validation planning
• rollout and rollback planning
• progress tracking against plan

The system must distinguish between:

• goal / intent
• project plan
• issue-backed work items
• execution state
• validation state
• completion state

---

10.8 Architecture Model

Each Master Project must maintain a canonical architecture model.

This model must be:

• editable by humans
• editable by the system
• versioned
• queryable
• usable during planning and coordination

The architecture model should capture:

• repositories
• services/applications
• dependencies
• interfaces/APIs
• integration points
• infrastructure relationships
• deployment boundaries
• CI/CD relationships
• shared components/libraries

The system should support two views:

• Declared Architecture: human-defined intended structure
• Observed Architecture: system-inferred structure from repos and pipelines

Concilium should surface drift between these where possible.

---

10.9 Memory and Knowledge

Concilium must maintain persistent memory at multiple levels:

• Master Project memory
• Repo Agent memory
• Specialist Agent memory
• Architecture memory
• Work history
• Validation history
• Issue-linked historical context
• Artifact references
• Event/audit trail

Memory must be durable across:

• sessions
• machines
• runtime restarts
• execution environments

The system should use a layered memory model that distinguishes among:

• operational state
• episodic/event memory
• knowledge documents and summaries
• large artifacts
• semantic retrieval indexes

Concilium must not rely on raw chat history as its only memory model.

---

10.10 Messaging and Coordination

Concilium must support structured inter-agent messaging.

Messages should support types such as:

• assignment
• plan request
• context package
• clarification request
• blocker
• dependency update
• execution update
• validation result
• escalation
• completion summary

Messages should be associated with:

• master project
• repo
• work item / issue
• sender
• recipient
• timestamps
• status
• referenced artifacts

Claude Code should later define the exact schemas, protocol, and lifecycle.

---

10.11 Source Control Coordination

Concilium must be source-control-aware.

It must support reasoning and workflows around:

• repo state
• branch strategy
• branch creation
• branch naming conventions
• work item to branch linkage
• PR generation or coordination
• cross-repo relationships
• merge readiness
• integration sequencing

GitHub should be treated as the first practical SCM target.

---

10.12 CI/CD Awareness

Concilium must incorporate CI/CD as a core delivery signal.

It must be designed to understand and reason about:

• pipeline status
• required gates
• test/build outcomes
• validation pass/fail signals
• release readiness
• failure escalation

The initial design should explicitly account for:

• Munitor
• CircleCI
• repo-specific pipeline patterns and conventions

CI/CD must feed back into planning and work status.

---

10.13 Runtime and Execution Environments

Concilium must support execution in:

• local workstation environments
• remote runners
• Kubernetes jobs
• hybrid combinations of the above

Best-practice design assumption:

• agent identities are durable
• runtime execution is generally on-demand
• state and memory persist independently of active runtime processes

Concilium should support policies for where work may run.

---

10.14 Human Governance

Concilium must support strong human control, including:

• approval checkpoints
• editable plans
• editable architecture
• manual overrides
• review of issue creation and decomposition
• review of branch/PR actions
• review of system conclusions and summaries

The system should optimize for explainability and operator confidence.

---

10.15 Auditability and Traceability

Concilium must preserve traceability among:

• project goals
• plans
• issue tracker items
• agent actions
• branches
• pull requests
• CI/CD outcomes
• validation results
• completion summaries
• architecture updates

This should support serious SDLC and compliance-minded workflows.

---

11. Non-Functional Requirements

Concilium should be:

• durable
• resumable
• auditable
• secure
• observable
• extensible
• machine-independent
• provider-agnostic where practical
• deterministic in workflow state transitions where possible
• robust across partial failures

The architecture should be designed to scale later to:

• more repos
• more agents
• more workflows
• more users
• more teams

without forcing a total redesign.

---

12. Proposed Conceptual Architecture

This section sets direction, not final implementation.

12.1 Control Plane

A central control application should manage:

• Master Projects
• repos
• agent identities
• plans
• work mappings
• issue mappings
• architecture state
• approvals
• audit history
• system configuration

This should be the canonical coordination layer.

12.2 Memory and Knowledge Layer

A layered persistence model should support:

• structured records
• event history
• knowledge docs
• summaries
• artifacts
• semantic retrieval

12.3 Orchestration Layer

A durable orchestration model should support:

• long-running workflows
• retries
• waiting states
• issue-driven progression
• approval waits
• CI/CD waits
• resumable execution

12.4 Agent Runtime Layer

A pluggable runtime layer should support:

• Master Agent
• Repo Agents
• Specialist Agents
• structured task routing
• on-demand execution
• durable identities and memory

12.5 Integration Layer

Integration adapters should be designed for:

• GitHub
• Jira
• GitHub Issues
• CircleCI
• Munitor

with future extensibility for additional systems.

12.6 Operator UX Layer

The user-facing layer should eventually support:

• dashboarding
• project status
• repo status
• architecture view/editing
• issue coordination
• approvals
• execution history
• agent messaging and state

---

13. Storage and Persistence Direction

The intended platform direction is:

• QQQ-based backend for canonical application/control data
• Postgres for structured persistent records
• S3-compatible object storage for larger artifacts and snapshots
• semantic/vector retrieval for knowledge recall
• durable persistence for orchestration state

Important design constraint:

• do not treat S3 alone as memory
• do not treat vector storage alone as memory
• do not treat conversation history alone as memory

Concilium should use layered memory and durable state separation.

---

14. MVP Direction

An initial MVP should likely include:

• create a Master Project
• attach 2 to 5 repos
• persist repo summaries
• persist a project summary
• define/edit a basic architecture model
• create or sync issue-backed work items
• produce a project-level plan
• decompose work into repo plans
• assign work to repo agents
• store messages and progress
• monitor CI/CD signals
• produce integrated project status

This is enough to prove the core coordination value.

---

15. Deferred / Later-Phase Capabilities

Likely later-phase capabilities:

• richer autonomous implementation
• advanced specialist agents
• release orchestration
• broader policy enforcement
• deep deployment automation
• multi-user collaboration
• enterprise-grade RBAC
• plugin marketplace

These should not block the initial foundation.

---

16. Deliverables Requested from Claude Code

Claude Code should use this proposal to generate and scaffold a serious initial project foundation.

At minimum, it should create:

Product / Planning Docs

• full PRD
• roadmap
• milestone plan
• backlog
• workflows
• ADRs
• architecture overview

Technical Design Docs

• component architecture
• domain model
• data model
• memory strategy
• orchestration strategy
• runtime model
• message protocol
• integration design

Repo Scaffolding

• README
• docs structure
• source layout
• package/module layout
• starter application skeleton
• config/environment templates
• testing structure
• issue templates
• contributor documentation

Developer Experience Assets

• local dev instructions
• examples
• architecture diagrams
• setup checklist
• initial task breakdown

---

17. Open Design Areas Claude Code Should Resolve

Claude Code should make specific recommendations for:

• implementation stack
• orchestration approach
• runtime model
• memory model
• domain model
• message protocol
• architecture graph representation
• tracker abstraction model
• repo lifecycle model
• MVP boundaries
• repo structure and scaffolding

Where multiple options exist, it should document tradeoffs and recommend one.

---

18. Success Criteria for Initial Output

The first Claude Code pass should leave the repo in a state where:

• the project vision is clearly documented
• the architecture direction is clear
• the domain model is defined
• initial implementation structure exists
• onboarding is straightforward
• the backlog is organized
• the project can immediately begin active development

---

19. Immediate Next Step

Claude Code should treat this document as the initial product handoff and expand it into:

• a detailed PRD
• a technical architecture
• domain model docs
• repo scaffolding
• an implementation roadmap
• initial GitHub-ready project assets