Core concepts
Agents & jobs
Once a theme is worth pursuing, VocxAI's agents take it from an idea to a reviewable pull request - researching your codebase, drafting a plan, and then writing and testing the actual code. Nothing here is instant or invisible: every step produces a job you can watch, and every plan waits for a human before any code gets written.
From theme to plan
Promoting a theme just adds it to the backlog as a feature - nothing gets drafted automatically. Each stage of the plan below is something you explicitly ask for, one at a time:
- Generate PRD - if GitHub is connected, an agent researches your connected repos for relevant context first; without it, the PRD is drafted without codebase grounding. This one action produces the product requirements document along with the architectural decisions and repo topology (which repos are involved, and how) that the plan depends on.
- Generate specs - once you're happy with the PRD, this breaks it into scoped, independently reviewable pieces of work.
- Create detailed tasks - each spec expands into concrete implementation tasks, grounded against your actual repo (verified file paths, existing patterns to follow) rather than guessed.
Architectural decisions raised along the way need to be reviewed before tasks can be generated - see Approval gates for what's actually enforced at each step.
Approve for build
This is the one deliberate, manual step in the whole pipeline: once a PRD and specs exist, Approve for build is what turns a reviewed plan into running agent jobs. Nothing before this point writes any code - PRDs, specs, and tasks are all just documents until someone approves. The moment you do, a job is queued for every spec ready to go.
What a job is
A job is one tracked run of an agent - it has a status (Waiting, Queued, Running, Done, or Failed), a live log, and (for build jobs) a branch and eventually a pull request URL. A feature can have several kinds of job behind it - codebase research, spec and task generation, one build job per spec, and a test job once a repo's builds finish - not just one.
Every job for every feature shows up on the Build agents board, grouped by what's waiting on dependencies, queued, running now, and completed - with live logs while something is running, and cancel/retry on jobs that need it.
How a build agent works
A build job runs in an isolated sandbox with a clone of your repo, with the same kind of access a developer would have - it can read, write, and edit files, run shell commands, and run your test/verification commands before calling itself finished. Once it's done, it opens the change as a normal pull request against your repo's default branch.
Manual tasks - the fast path
Not everything needs a full PRD. The Issues board also supports manual tasks: write a title and description, pick which repo(s) it applies to, and drag it into In Progress - that action alone starts a build agent immediately, using the same runtime and the same PR-creation flow as the full pipeline, just without a PRD, specs, or a decision review first. It's meant for smaller, well-understood work where the planning stages would just be overhead - the pull request review gate still applies either way.
What "Done" means
A feature moves to Done once every job tied to it has finished running - including jobs that failed. Done tells you the pipeline finished, not that everything succeeded or that anything shipped. If you want to know whether a feature actually landed cleanly, check the Build agents board for any failed jobs and your GitHub repo for the resulting pull request(s).