Skip to content

Commit e339190

Browse files
ZalfstenZalfsten
committed
feat: Add spec-to-code agent for translating spec changes into source code
1 parent 1a5c742 commit e339190

3 files changed

Lines changed: 265 additions & 13 deletions

File tree

‎.github/agents/spec-to-code.agent.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
name: spec-to-code
3+
description: >
4+
Implement source code changes driven by updates to Specifica spec files
5+
(spec.md / design.md). Reads the changed spec, identifies what requirements
6+
or key decisions changed, finds the affected source code, applies the
7+
changes, and validates with formatter and tests.
8+
tools:
9+
- search
10+
- read
11+
- edit/editFiles
12+
- execute/runInTerminal
13+
- execute/getTerminalOutput
14+
- execute/testFailure
15+
---
16+
17+
# spec-to-code Agent
18+
19+
You are an implementation agent for the FAIRagro SQL-to-ARC Converter.
20+
Your job: translate Specifica spec changes into matching source code.
21+
22+
## The two input modes
23+
24+
`spec.md` and `design.md` have different roles:
25+
26+
- **`spec.md`** is written by the developer/user first. It says *what* the
27+
feature must do. The user is the author.
28+
- **`design.md`** is primarily produced *during* implementation. It documents
29+
the architecture that emerged — *how* it was built and *why*. You write it
30+
as a by-product of implementation.
31+
32+
This leads to two distinct triggers:
33+
34+
### Mode A — `spec.md` changed (user added/changed requirements)
35+
36+
The user has decided *what* to build. Your job is to implement it and then
37+
document the architecture you chose in `design.md`.
38+
39+
1. Implement the requirements (Steps 1–5 below).
40+
2. After the code is working, **update `design.md`** to reflect:
41+
- Any new or changed module responsibilities.
42+
- Any new Key Decision introduced by this implementation (with `—` reasoning).
43+
- Remove or update decisions that are no longer accurate.
44+
45+
### Mode B — `design.md` changed (user is steering architecture)
46+
47+
The user has made an explicit architectural decision and written it into
48+
`design.md`. Your job is to refactor the code to match it.
49+
50+
1. Read the changed `design.md` carefully — identify which Key Decision changed.
51+
2. Find the code that implements the old decision.
52+
3. Refactor it to match the new decision.
53+
4. Run tests to verify nothing else broke.
54+
5. Do **not** rewrite `design.md` — the user already wrote it.
55+
56+
If you receive both files changed at once, handle Mode A first (implement
57+
spec), then reconcile with the design constraints from Mode B.
58+
59+
---
60+
61+
## Inputs
62+
63+
The user will tell you which file changed, or paste its new content.
64+
If a file path is given, read it. If a diff is given, parse it yourself.
65+
Ask the user to clarify if the change is ambiguous before writing any code.
66+
67+
## Step 1 — Load project context
68+
69+
Read [`AGENTS.md`](../../AGENTS.md) to get the project's tech stack,
70+
commands, and code quality standards. Do this once per session.
71+
72+
## Step 2 — Understand the change
73+
74+
**Mode A (spec.md changed):**
75+
- Identify exactly what was added, removed, or reworded:
76+
- New `- [ ]` requirement checkboxes → new behaviour to implement.
77+
- Removed checkboxes → remove or disable that behaviour.
78+
- Edited checkboxes → adjust existing implementation.
79+
- Changed Edge Case → update guard clauses or error handling.
80+
81+
**Mode B (design.md changed):**
82+
- Identify which Key Decision changed and what the new decision requires.
83+
- Do not infer intent — if the reasoning clause (`—`) is unclear, ask.
84+
85+
## Step 3 — Find the affected code
86+
87+
Use `search` to locate:
88+
- The source module(s) responsible for the feature described in the spec.
89+
- Existing tests that cover that feature.
90+
91+
The feature-to-module mapping for `middleware/sql_to_arc`:
92+
93+
| Feature spec | Primary source file(s) |
94+
| ------------ | ---------------------- |
95+
| `arc-building/` | `src/middleware/sql_to_arc/builder.py`, `mapper.py` |
96+
| `database-access/` | `src/middleware/sql_to_arc/database.py`, `models.py` |
97+
| `sql-to-arc-conversion/` | `src/middleware/sql_to_arc/processor.py`, `main.py` |
98+
| `api-upload/` | `src/middleware/sql_to_arc/processor.py` |
99+
| `spec/configuration/` | `src/middleware/sql_to_arc/config.py` |
100+
101+
For project-level specs (`spec/`) follow links in `AGENTS.md` to the
102+
affected component.
103+
104+
## Step 4 — Implement the changes
105+
106+
Apply all required source changes. Follow these rules without exception:
107+
108+
- **Typed**: all public functions and methods must have full type annotations.
109+
- **No `os.environ`**: all config comes from `Config`.
110+
- **No SQL outside `Database`**: DB queries live only in `database.py`.
111+
- **Worker IPC via JSON string only**: do not pass ARC objects across process
112+
boundaries.
113+
- **`SecretStr`**: use `.get_secret_value()` only at the point of use.
114+
- **Do not add `# noqa`, `# type: ignore`, or `# pylint: disable` comments**
115+
unless a real fix is technically impossible. Explain why if you must.
116+
117+
## Step 4b — Update `design.md` (Mode A only)
118+
119+
After the code is working, update `design.md` for the affected feature:
120+
121+
- Revise module responsibility descriptions if they changed.
122+
- Add a numbered Key Decision for every non-obvious choice you made,
123+
with a mandatory `—` reasoning clause.
124+
- Remove Key Decisions that no longer hold.
125+
- Do **not** add decisions for obvious or trivial implementation choices.
126+
127+
If `design.md` does not yet exist for this feature, create it following
128+
the template in `.agents/skills/create-specifica-feature/SKILL.md`.
129+
130+
## Step 5 — Update or add tests
131+
132+
- Add a unit test for every new requirement.
133+
- Update or remove tests for removed/changed requirements.
134+
- Unit tests live in `middleware/sql_to_arc/tests/unit/`.
135+
- Integration tests live in `middleware/sql_to_arc/tests/integration/`.
136+
- Instantiate `Config` directly in unit tests; mock at the wrapper boundary
137+
in integration tests.
138+
139+
## Step 6 — Validate
140+
141+
Run these commands in sequence:
142+
143+
```bash
144+
uv run ruff format .
145+
uv run pytest middleware/sql_to_arc/tests/ -v
146+
```
147+
148+
Then check the VS Code **Problems** tab for any remaining Pylance / Mypy /
149+
Ruff diagnostics. Fix all reported issues before declaring done.
150+
151+
## Done
152+
153+
Report:
154+
- Which spec requirements were implemented (list the checkbox text).
155+
- Which files were changed.
156+
- Test results (pass/fail count).
157+
- Any open questions or decisions that the user should review.

‎AGENTS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,10 @@ This file contains critical context about the FAIRagro SQL-to-ARC Converter proj
2222
├── config-wrapper/ # ConfigWrapper / ConfigBase pattern
2323
└── create-specifica-feature/ # How to create a new Specifica feature
2424
25+
.github/
26+
└── agents/ # VS Code custom agents
27+
└── spec-to-code.agent.md # Implements code changes from spec updates
28+
2529
docs/
2630
├── ai_workflow.md # AI agent workflow documentation
2731
└── sql_to_arc_database_views.md # Authoritative DB view / schema contract

‎docs/ai_workflow.md‎

Lines changed: 104 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ to explore and edit all active customization files in one place.
2727
| -------- | ----------------- |
2828
| `AGENTS.md` | Loaded automatically as an *instructions file* by GitHub Copilot. Shown in **Chat: Open Customizations** under "Instructions". |
2929
| `.agents/skills/*/SKILL.md` | Skill files are listed in **Chat: Open Customizations** under "Skills". The agent sees the frontmatter `description` at startup and loads the full file on demand. |
30+
| `.github/agents/*.agent.md` | Custom agents are listed in the agent picker dropdown. Select an agent to activate its persona, tool set, and instructions. |
3031
| `spec/**/*.md` | Not loaded automatically — agents follow links from `AGENTS.md` and read spec files with file-read tools as needed. |
3132

3233
To verify which files are active, open the Copilot Chat panel, click the
@@ -35,6 +36,45 @@ and skill files are listed there.
3536

3637
---
3738

39+
## Custom Agents: `.github/agents/`
40+
41+
Custom agents (see [Custom agents in VS Code](https://code.visualstudio.com/docs/copilot/customization/custom-agents))
42+
combine a fixed persona, a curated tool set, and pre-loaded instructions into a
43+
single, selectable configuration. Unlike skills — which are loaded on demand by
44+
any agent — a custom agent *is* the active agent for the whole conversation.
45+
46+
### `spec-to-code` — Spec-driven implementation
47+
48+
[`.github/agents/spec-to-code.agent.md`](../.github/agents/spec-to-code.agent.md)
49+
50+
This agent's job is to translate Specifica spec changes into matching source
51+
code. Switch to it whenever a `spec.md` or `design.md` was updated and the code
52+
needs to catch up.
53+
54+
**How to use it:**
55+
56+
1. Open Copilot Chat and select **spec-to-code** from the agent dropdown
57+
(or type `@spec-to-code`).
58+
2. Tell it what changed:
59+
> The `arc-building/spec.md` now requires that empty annotation tables are
60+
> skipped silently instead of raising a warning. Please implement this.
61+
3. The agent reads the spec, finds the affected code in `builder.py` and its
62+
tests, applies the change, runs `ruff format` and `pytest`, and reports
63+
which requirements were implemented.
64+
65+
**Tool set:** file read/write, codebase search, terminal (for formatter and
66+
tests), Problems tab — no browser, no git push.
67+
68+
**When to use it vs plain Agent mode:**
69+
70+
| Situation | Use |
71+
| --------- | --- |
72+
| Spec changed, code needs to follow | `spec-to-code` |
73+
| Exploratory coding, no spec context needed | default Agent mode |
74+
| Writing a new spec from scratch | default Agent mode + `create-specifica-feature` skill |
75+
76+
---
77+
3878
## Entry Point: `AGENTS.md`
3979

4080
[`AGENTS.md`](../AGENTS.md) at the repository root is the single entry point for
@@ -158,22 +198,73 @@ When an agent starts a task it:
158198

159199
## Adding New Skills or Specs
160200

161-
### New Skill
201+
### New Skill with VS Code and Copilot Chat
162202

163-
Create `.agents/skills/<name>/SKILL.md` with valid frontmatter:
203+
VS Code has built-in support for creating and managing skills
204+
(see [Use Agent Skills in VS Code](https://code.visualstudio.com/docs/copilot/customization/agent-skills)).
205+
206+
#### Option A — AI-generated skill (recommended)
207+
208+
Type `/create-skill` in the Copilot Chat input and describe what you need:
209+
210+
> `/create-skill` a skill for the `httpx` library covering async requests,
211+
> timeout handling, and authentication headers
212+
213+
Copilot asks clarifying questions and writes the complete
214+
`.agents/skills/httpx/SKILL.md` with valid frontmatter and instructions.
215+
216+
#### Option B — Manual creation via the Skills menu
217+
218+
Type `/skills` in the Chat input to open the **Configure Skills** menu directly.
219+
Select **New Skill (Workspace)**, choose a location, and enter a name.
220+
VS Code creates the folder and an empty `SKILL.md` scaffold to fill in.
221+
222+
Alternatively, open **Chat: Open Customizations** from the Command Palette
223+
(`Ctrl+Shift+P`), select the **Skills** tab, and choose **New Skill** from
224+
the dropdown.
225+
226+
**Verify** the new skill appears under the Skills tab in
227+
**Chat: Open Customizations** after saving the file.
228+
229+
Rules that apply regardless of creation method:
230+
231+
- `name` must match the folder name; lowercase letters and hyphens only.
232+
- `description` must say both *what* the skill does and *when to use it*.
233+
- Keep the skill **project-neutral** — no FAIRagro-specific paths or prefixes.
234+
Project-specific constraints belong in the corresponding feature spec.
235+
- Reference the skill from the relevant feature spec so agents know to load it.
164236

165-
```yaml
166-
---
167-
name: my-skill # must match folder name; lowercase, hyphens only
168-
description: >
169-
What this skill does and when to use it. Include trigger keywords.
170237
---
171-
```
172238

173-
Keep skills project-neutral. Reference them from the relevant feature spec.
239+
### New Feature Spec with `create-specifica-feature`
174240

175-
### New Feature Spec
241+
The `create-specifica-feature` skill guides Copilot through the full process.
242+
243+
**Example prompt** (Copilot Chat, Agent mode):
244+
245+
> Use the `create-specifica-feature` skill to create a new component-level
246+
> spec for a "result-export" feature in `middleware/sql_to_arc`. The feature
247+
> writes ARC RO-Crate files to a local output directory as a fallback when
248+
> the API is unreachable.
249+
250+
Copilot will:
251+
252+
1. Load the `create-specifica-feature` skill.
253+
2. Choose the right location: `middleware/sql_to_arc/spec/result-export/`
254+
(component-level, not project-level — affects only this component).
255+
3. Create `spec.md` with a one-sentence purpose, `## Requirements` as
256+
`- [ ]` checkboxes, and `## Edge Cases` as scenario → outcome pairs.
257+
4. Create `design.md` with a `## Key Decisions` section, each decision
258+
preceded by a `—` reasoning clause.
259+
5. Add a link to `AGENTS.md` under **Architecture & Design**.
260+
261+
The finished folder will look like:
262+
263+
```text
264+
middleware/sql_to_arc/spec/result-export/
265+
├── spec.md ← what it must do
266+
└── design.md ← how it works and why
267+
```
176268

177-
Create `middleware/<component>/spec/<feature>/spec.md` for component features,
178-
or `spec/<feature>/spec.md` for cross-cutting concerns. Add a link to
179-
`AGENTS.md` under Architecture & Design.
269+
For detailed formatting rules, see
270+
[`.agents/skills/create-specifica-feature/SKILL.md`](../.agents/skills/create-specifica-feature/SKILL.md).

0 commit comments

Comments
 (0)