How ar4mirez/samuel works
Samuel is a Go CLI framework manager and autonomous AI coding loop. Its principal workflow initializes a project with framework guidance, lets users discover and add components, then bootstraps and runs task-driven coding iterations with status and task-management commands. Separate CLI capabilities handle updates, health checks, configuration, synchronization, and version comparisons; the v4 orchestrator installs the gstack, gbrain, and Samuel-skills bundle. The README documents these product flows; source excerpts confirm selected command-to-core calls, while unsampled command internals are represented only where documented.
Main entry points: root.go Command router · auto.go Run lifecycle commands · orchestrator.go Bundle orchestrator · registry.go Framework content
Components 20
CLI workflows
- CLI entry
cmd/samuel/main.go - Command router
internal/commands/root.go - Component discovery
internal/commands/search.go - CLI output
internal/ui/output.go
Autonomous loop
- Run lifecycle commands
internal/commands/auto.go - Task management
internal/commands/auto_task_handlers.go - Iteration engine
internal/core/auto_loop.go - PRD and task state
internal/core/auto_tasks.go
Framework management
- Component add/remove
internal/commands/add.go - Project initialization
internal/commands/init.go - Framework content
internal/core/registry.go - Framework update
internal/commands/update.go - Installation health
internal/commands/doctor.go - Admin operations
internal/commands/admin.go - Folder synchronization
internal/core/sync.go
Install orchestration
- Bundle orchestrator
internal/orchestrator/orchestrator.go - Bundle components
internal/orchestrator/component_samuel.go - Embedded skills
internal/skills/embed.go
Other components
- Project user
- AI coding tool
Connections 23
- Project user → CLI entry: invokes
- CLI entry → Command router: executes
cmd/samuel/main.go - Command router → Component discovery: routes discovery
- Command router → Component add/remove: routes changes
- Command router → Project initialization: routes init
- Command router → Framework update: routes update
- Command router → Installation health: routes checks
- Command router → Admin operations: routes admin
- Component discovery → Framework content: searches catalog
internal/commands/search.go - Component add/remove → Framework content: manages components
- Project initialization → Framework content: installs framework
- Framework update → Framework content: updates framework
internal/commands/update.go - Installation health → Bundle orchestrator: checks bundle
- Admin operations → Folder synchronization: runs sync
- Project initialization → Bundle orchestrator: installs bundle
- Bundle orchestrator → Bundle components: installs components
- Bundle orchestrator → Embedded skills: uses embedded content
- Project user → Run lifecycle commands: starts loop
- Run lifecycle commands → Iteration engine: runs iterations
- Run lifecycle commands → PRD and task state: loads loop state
- Task management → PRD and task state: reads and updates
internal/commands/auto_task_handlers.go - Iteration engine → AI coding tool: invokes coding tool
- Run lifecycle commands → CLI output: reports status