Archived
james.maesandClaude Opus 4.6
4f29f682d2
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
808 lines
19 KiB
Markdown
808 lines
19 KiB
Markdown
# 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
|