A PAS Code project is prepared for an AI coding assistant. It carries the conventions of the project and the skills that describe how work in a PAS Code project is done (refer to Working With Skills and Skills for more details). Your assistant loads a skill when your request matches its description, so you describe your task in your own words instead of naming a command.
The features are then developed according to the spec-driven workflow, which this page describes from your side of the conversation. Your assistant follows the workflow, and you decide what is built.
What a Project Provides to an Assistant
Every project you create with pas new contains the files that tell an assistant how to work in it:
|
File or folder |
What it provides |
|---|---|
|
.agents/AGENTS.md |
The conventions of your project: its structure, the path aliases for cross-package imports, the test runner, and the rule that components are scaffolded with generators. |
|
.pas/skills-sources.json |
The skill sources, and the assistants the skills are linked for. |
|
The skills folder of your assistant |
The linked skills. These are generated copies. |
|
Your own rules, which complete or override the rules PAS Code ships. |
|
SPEC.md files |
What the code in a folder must achieve. |
The skills arrive with the dependencies: npm install runs pas-link-skills as its postinstall script and links the declared skills into the folders where your assistant discovers them. Refer to Working With Skills and to Skills for further information.
Components are always scaffolded with the PAS CLI, never written by hand. The build pipeline and the platform rely on the structure the generators produce.
Working Through the Phases
Your assistant names the phase it is in and the skill it is using, so you can follow along. At the end of each phase it stops and asks you.
|
Phase |
Result |
Applied Rules |
|---|---|---|
|
Specification |
A SPEC.md that describes what the code must achieve. |
Specification rules |
|
Code |
The implementation of the approved specification. |
Code rules |
|
Documentation |
The README.md and AGENTS.md files that describe how the code is used. |
Documentation rules |
Work through a feature as follows:
-
Describe the feature in your own words. Your assistant starts in the specification phase.
-
Read the specification it presents. Give your remarks until it describes what you want.
-
Approve the specification, then ask for the code.
-
Review the code, approve it, then ask for the documentation.
-
Approve the documentation.
Two effects of the workflow are easier to recognize once you have seen them:
-
A phase that does not advance is waiting for an explicit approval, not for more detail.
-
A remark you make in the code phase can send the workflow back to the specification. Your assistant is persisting your remark, not losing the thread.
Scaffolding With an Assistant
When a feature needs a new component, your assistant scaffolds it with the PAS CLI instead of writing project files by hand. The scaffolding skills call the same commands you would call yourself:
|
What you ask for |
What your assistant does |
|---|---|
|
A new backend API |
Runs |
|
A new frontend application |
Runs |
|
An AI feature in a service |
Runs |
|
A group of components that are deployed together |
Runs |
These are examples, not fixed phrases. Your assistant selects a skill by matching your request against its description, so a request for a REST API and a request for a microservice reach the same skill.
Scaffolding belongs to the code phase. Without an approved SPEC.md on disk, your assistant does not run a generator. It stops and returns to the specification phase. This is intended behavior, not a defect. For the reason, refer to Working With Skills.
The scaffolding skills create a new standalone component. A controller, a route, or a provider inside an existing service is an ordinary change to that service, not a scaffolding task.
Setting Rules
The rules PAS Code ships apply to every project. To complete or override them for your project, add the matching file to the .agents folder:
-
.agents/code-rules.md
-
.agents/specification-rules.md
-
.agents/documentation-rules.md
Where your rule conflicts with a rule PAS Code ships, your rule applies.
Two rules apply to the files on your disk:
-
The linked skills are generated copies. An edit is lost the next time the skills are linked. To change a skill that PAS Code ships, edit it in its source package and link again.
-
A rule you state in a conversation applies to that conversation only. Write it into a rule file to keep it.
Reviewing a Change Set
Before you open or merge a merge request, ask your assistant to review the pending changes. The review checks your change set against the SPEC.md files that govern it and against the PAS rules.
The review reports:
-
The findings, grouped as blockers, should-fix items, and nits.
-
A merge-readiness verdict.
It checks that a governing SPEC.md exists and that the code implements what it requires, that the change follows the code rules, that new behavior has tests, and that lint and build pass.
The most common blocker is code that no SPEC.md covers, which means the workflow was skipped.