How ehsanrs2/projectctl works
ProjectCTL is a local-first, Git-native control plane for AI-assisted engineering. Its user workflow begins with project onboarding and task-authority selection, then gathers task and quota state for deterministic planning, governs isolated worker execution, independently verifies results, and controls evidence-based integration or recovery. Separate capabilities include parallel execution, project health checks, task-system integrations, and read-only lifecycle auditing. The graph uses documented product flows and source-index references; unsampled implementation details are represented only at supported directory paths, and the M6 trace collector remains explicitly unavailable.
Main entry points: app.py CLI Commands · execution.py Run Lifecycle · service.py Quota-aware Scheduler · runs.py Run State Store
Components 20
User Entry
- CLI Commands
projectctl/cli/app.py - Project Onboarding
projectctl/application/onboarding.py
Planning and Governance
- Project Config and State
projectctl/project/loader.py - Task Snapshot
projectctl/application/tasks.py - Quota-aware Scheduler
projectctl/scheduler/service.py - Quota Policy
projectctl/quota/manager.py - Parallel Planning
projectctl/parallel/service.py
Execution and Evidence
- Run Lifecycle
projectctl/application/execution.py - Worker Adapters
projectctl/workers - Independent Verification
projectctl/verification/runner.py - Review and Delivery
projectctl/application/review_delivery.py
Authority and Delivery
- Task Authority
projectctl/integrations/task_authority.py - Task Providers
projectctl/integrations - Git Operations
projectctl/git
State and Observability
- Run State Store
projectctl/storage/runs.py - Project Health Checks
projectctl/doctor/service.py - Lifecycle Audit
projectctl/telemetry/lifecycle_reader.py - Trace Snapshot
projectctl/trace/snapshot.py
Other components
- Engineer
- Task Systems
Connections 22
- Engineer → CLI Commands: invokes
README.md - CLI Commands → Project Onboarding: starts setup
projectctl/cli/app.py - CLI Commands → Task Snapshot: requests tasks
projectctl/cli/app.py - CLI Commands → Project Health Checks: requests checks
README.md - CLI Commands → Lifecycle Audit: requests audit
README.md - Project Onboarding → Project Config and State: configures project
- Task Snapshot → Task Authority: resolves reader
projectctl/application/tasks.py - Task Authority → Task Providers: selects provider
- Task Providers → Task Systems: reads tasks
- Quota-aware Scheduler → Quota Policy: evaluates quota
projectctl/scheduler/service.py - Quota-aware Scheduler → Task Snapshot: uses task snapshot
- Quota-aware Scheduler → Project Config and State: uses project state
projectctl/scheduler/service.py - Quota-aware Scheduler → Run Lifecycle: recommends work
- Parallel Planning → Project Config and State: builds plan from
projectctl/parallel/service.py - Run Lifecycle → Worker Adapters: dispatches worker
- Run Lifecycle → Run State Store: records lifecycle
- Run Lifecycle → Independent Verification: requests verification
- Run Lifecycle → Review and Delivery: governs integration
README.md - Review and Delivery → Git Operations: uses Git delivery
projectctl/application/review_delivery.py - Independent Verification → Run State Store: records evidence
- Lifecycle Audit → Run State Store: reads run history
- Trace Snapshot → Run State Store: reads run data
projectctl/trace/snapshot.py