--- title: From concept to seeded work scope: 3dmk type: documentation subject: concept-to-seed group: Overview status: current version: "2.1.3" source: https://3dmk.com/documentation#concept-to-seed author: Nick Olson contact: email: 3dmk@3dmk.com site: https://3dmk.com license: CC BY 4.0 license_url: https://creativecommons.org/licenses/by/4.0/ attribution: Nick Olson, 3dmk.com --- # From concept to seeded work Every project in this harness travels the same road from an idea to a queue of work. A chain of documents fixes each decision before any code exists. The developer approves each document, and the agent checks it against the document before it. The last step seeds Scrolls with work items that an agent can run without guessing. The example on this page and the next two is Trailcast, a website for trail conditions. It has a public site, an API, and two daemons that run on a schedule. ## The example Trailcast shows the current state of each trail in a region. Its parts live in two repositories, and each repository gets its own document chain and its own graph: - `trailcast-web`: the public site, with a page for each trail and a map - `trailcast-api`: the API, plus a feed daemon and a summary daemon The feed daemon pulls weather and closure reports from an outside feed every 15 minutes and stores each reading. Each night, the summary daemon rolls the day’s readings into one summary per trail. The API serves trails, readings, and summaries to the site. ## Concept A project starts as a conversation, not a document. The developer describes the idea in plain terms. The agent asks what the project must do, who uses it, and what it must never do. No code exists yet, and no document. The concept ends when the developer runs `trigger new project` with a theme and a project name. A theme that does not exist yet comes first, through `trigger new theme`. ## The document chain The trigger loads its process from Seele and follows it step by step. It first searches for documents that already exist and shows the result as a table. It then stops until the developer confirms. Vision and Product are optional, and the developer decides whether the project needs each one. *Figure: Each one approved, then checked against the one before. The drawing is on the page.* Each document fixes one layer of the project. | Document | What it fixes | |---|---| | Overview | What the project is, its current state, its stack, its libraries, and its document index | | Vision | Purpose, users, goals, non-goals, and key constraints | | Product | Features, user flows, interface behavior, and what is out of scope | | Technical | Architecture, processing, data model, contracts, and publishing | | Magi | A machine-readable graph of every running part and every boundary between parts | | Planning | Agent routing, current state, the Scrolls seed, and the epics with their work items | Every document goes through the same loop. The agent walks through the document’s purpose and required sections with the developer. It gathers what it needs and writes a draft to Seele. Revisions continue until the developer approves. The agent then checks the draft against the document before it. A change there sends the check back up the chain until nothing moves. ## Technical Technical is where open choices end. Before it writes a line, the agent loads the standards for each of the project’s languages: - The language standard: runtime, async model, project structure, and build - The library matrix: approved libraries, blocked versions, and upgrade holds - The scaffold: the directory tree for the project’s type - The integration standard: how a service joins the shared platform The draft follows them. Every dependency carries an exact version pin. Each design choice becomes an architecture decision with its rationale and a rule the code must follow. For Trailcast, the standards fix the API framework, the database driver, the log format, and the test layout. The daemons follow the same rules as the API. The agent checks the finished draft twice: against the standards it loaded, and against Product, Vision, and Overview. The repository must exist in the Registry before the chain goes further. If it does not, `trigger new repo` registers and creates it first. ## Magi Magi restates Technical as a graph that a script can check. Each running part is a node with a type: a service, a process, an interface, a data store, an application, or a view. Each relationship is a typed edge. Every edge that carries data names the model that crosses it. *Figure: The trailcast-api graph. The drawing is on the page.* Every value in the graph uses the project’s own vocabulary: class paths, table names, method names, and routing keys. An agent that reads the graph can search the code for those exact strings. A shared system, such as the database, carries the same identifier in every graph that uses it. Two projects that touch the same table point at the same node. The first graph comes from the approved Technical document. From then on, the code is the test. A node without running code leaves the graph, and planned work stays in Planning. That rule makes the graph a lock. It holds only what was defined and built, and every later change is measured against it. ## Planning With Technical and Magi approved, the agent updates the Overview with the final stack, libraries, and document index. Planning comes last. It turns the design into ordered work, and its Scrolls seed holds two tables: the initiative’s identity and an inventory of its epics. *A figure on the page draws this.* The epics follow fixed rules. Foundation comes first: the repository, the schema, and the bootstrap. Each epic holds one concern and, where it can, one repository. Each epic also states its exit criteria, so done has a definition before work starts. Every work item in an epic’s table carries a type, a name, a title, a priority, a size, and a repository. ## Seeding The scrolls trigger, `trigger scrolls`, moves the plan into Scrolls. It loads Planning and Technical first. If either is missing or fails the documentation standards, the trigger stops and names the gap. A gap means an earlier step was skipped, and the trigger does not fill it with a guess. The trigger then checks the seed against live Scrolls data. It presents a dry run: the initiative, the new epics, and a count of work items per epic. It creates nothing until the developer confirms. Each item then lands with what an agent needs to run it alone: - A type: a story for documentation and a task for code, never a mix - A short description for listings and the dashboard - An agent specification with file paths, signatures, configuration keys, and Technical references - The items that must finish before it starts - An acceptance-criteria subtask and a testing subtask on every task Each seeded epic then moves from planning to ready. Trailcast now has a queue in place of an idea. The next page follows that queue to production.