Project Architect

What job it is for, and why this one

Reach for this when the expensive mistake is a wrong shape rather than a wrong line: a new service, a small tool that has to fit an existing codebase, or a rewrite where you have a rough idea and no written decisions. Its method is documentation first — it interviews you, then writes the plan down, then produces a single prompt meant to build the thing in one pass.

The reason to use it rather than a chat message is the ordering. Its own instructions make the documents sequential and forbid skipping ahead, so the specification exists before the implementation plan and the implementation plan before the task list. A single long prompt cannot give you that guarantee, because nothing stops you from asking for the task list first.

When it is the wrong tool

It is a planning surface, not a builder. If you already know the shape and the work is a handful of edits, the interview is pure overhead: it will ask about project type, audience, scope and stack before it writes anything, and you will be answering questions you had already settled.

It is also the wrong fit when the real uncertainty is not structural. If the risk is an unproven library, a third-party API or a performance question, a set of planning documents will read well and settle nothing; that risk has to be retired by a small experiment first, and the plan written afterwards.

Its plugin awareness is written for one ecosystem. The instructions tell the agent to look for other installed plugins and to fold their standards into the plan, which is useful there and simply inert in a harness with no plugin registry.

What it needs, and what comes back

The prerequisite is a conversation, not an input file. Before it writes anything it wants the elevator pitch, the audience, the project type, whether this is a first version or the whole product, and a stack direction — or an explicit request to help choose, which switches it into a selection flow that presents options with trade-offs rather than picking for you.

The output is written to files under the documentation folder of the project in the working directory, not into the conversation: a specification of what the project is, an implementation document covering structure, dependencies and module interfaces, an ordered task list whose items are sized to be finished in one agent session, and an optional branding document. The last artefact is a single self-contained prompt meant to carry everything needed to build the project without the other documents open.

Two limits are worth knowing before you start. The file layout and the ordering rules are instructions from the author, so a harness that does not follow them will produce the same documents in a different order and with less consistency. And the naming of the final prompt is a convention rather than a contract: nothing checks that the prompt it writes is genuinely self-contained, so that is the part worth reading yourself.

Tool support, permissions and dependencies

The pinned front matter claims compatibility with any coding agent that can read and write files and ask the user questions, and names two agents as its optimised targets with several others listed as also compatible. That is the claim of the author; this listing does not test agents, so treat it as the starting point for your own check rather than as a result.

The permission footprint is wider than it first appears, and the reason is file writing. The instructions tell the agent to save every document into the working directory, so running it inside an existing repository will add a folder of planning files to that repository. A harness that also lets the agent choose its own file locations can put them somewhere you did not expect. Decide where the output should land, and whether that directory is committed, before the first run.

The interactive parts are tool-specific. Several phases are built around asking the user to pick from a short list, and the instructions name that questioning tool explicitly. Where it is unavailable the flow degrades into freeform questions, which still works but produces the slower, more ambiguous interview the skill was written to avoid. There is no network dependency, no script to run and no package to install for the planning itself.

Compared with just writing a prompt

If your task is one file or one afternoon, a careful prompt you write yourself will be faster and you will understand every decision in it. What you lose is the checklist: the interviewer is there to surface the questions you did not think to ask, and a single prompt encodes only the questions you already had.

If instead you have already written the plan — a real specification and an ordered task list — this skill adds little beyond reformatting it, and it may reorder decisions you made deliberately. The honest test is whether you can currently hand your plan to somebody else and have them build from it without asking you anything. If you can, you do not need this.

How to check the result yourself

The documents are the deliverable, so check them as documents before you let anything be built from them.

• Read the task list alone and ask whether each item is finishable without a conversation. An item that says to set up the backend is not; one that names the files and the acceptance is.
• Search the specification for a decision you remember making, and check that the document states it and the reason. A plan that records conclusions without reasons cannot be reconsidered later.
• Open the final prompt on its own and try to build from it without the other files. Every time you have to go back to a document, that is a gap the prompt claims not to have.
• Check that nothing in the plan contradicts the recorded scope. An out-of-scope list that the task list ignores is the most common way these documents disagree with each other.

Source, version and what was actually read

The judgements above were made against one fixed version of the project, and the commit shown above is that version. If the record later moves to a different commit, this guide stops being shown rather than being shown against code nobody re-read.

What was read for this guide: the entry file of the project at that commit, which carries the front matter, the phase list, the operating rules and the output pipeline. That is the whole basis. The companion documents named inside the entry file were not opened, no file was installed or executed, no dependency was resolved and no agent was run. Statements about how the four documents come out in practice are therefore reasoning about the instructions, not observations of output.