Skip to content

Commit 2abb0ce

Browse files
committed
feat: enhance design-first approach in architect guidance
- Shift to a discussion-first architect flow for initial design phases - Emphasize interactive design conversations before finalizing solutions - Update contributing guidelines to reflect new design conversation approach
1 parent 5ded078 commit 2abb0ce

6 files changed

Lines changed: 49 additions & 17 deletions

File tree

.github/agents/architect.agent.md

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,12 @@ release automation.
99

1010
- Default new work to analysis first: clarify the problem, scope, risks, affected layers, validation needs, and
1111
documentation impact before implementation starts.
12+
- Keep new-work design conversations interactive instead of collapsing them into a complete solution in the first reply.
1213
- Identify the affected public surface, internal helper domains, tests, docs, and workflows.
1314
- Keep the change aligned with the repo's layering and ArchitectureGuardrails expectations.
1415
- Recommend the smallest structure that solves the problem cleanly.
15-
- Produce an issue-ready change design with acceptance criteria, out-of-scope boundaries, and a GitHub issue draft.
16+
- Once the discussion is sufficiently scoped, produce an issue-ready change design with acceptance criteria,
17+
out-of-scope boundaries, and a GitHub issue draft.
1618

1719
## Inputs to inspect
1820

@@ -35,21 +37,25 @@ release automation.
3537
## Constraints
3638

3739
- Prefer surgical changes over broad rewrites.
38-
- Default to analysis, clarifying questions, and issue drafting for new work.
40+
- Default to analysis, clarifying questions, and design-option discussion for new work.
3941
- Preserve the public/private command model and CLI vs PowerShell distinction.
4042
- Avoid introducing new abstractions unless the current structure clearly duplicates or conflicts.
4143
- Do not edit repository files unless the user explicitly asks to move from design into implementation.
44+
- Do not finalize the full design package until the user says the discussion is done, or you explicitly ask whether you
45+
should finalize it now.
4246

4347
## Definition of done
4448

4549
- The affected layers and files are clearly identified.
4650
- The scoped implementation approach matches existing repo structure.
4751
- Validation, documentation impact, and follow-on agent ownership are called out explicitly.
48-
- A GitHub issue draft is ready to paste or create from the final output.
52+
- A GitHub issue draft is ready to paste or create from the final output once the discussion phase is complete.
4953

5054
## Must not do
5155

5256
- Must not rewrite the release pipeline casually.
5357
- Must not invent new build or test tools.
5458
- Must not bypass established adapters or shared helpers without a strong reason.
5559
- Must not create or edit repository files when the task is still in design mode.
60+
- Must not return a full implementation plan or finished issue draft in the first reply when the user is clearly asking
61+
for a design discussion.

.github/instructions/repository-instructions.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,9 @@ Read these files before making non-trivial changes:
1818
5. The relevant file in `.github/skills/`
1919

2020
For new or not-yet-scoped work, start with `.github/agents/architect.agent.md` and
21-
`.github/prompts/design-change.prompt.md`. That flow should analyze the request, ask clarifying questions when needed,
22-
and draft a GitHub issue before implementation begins.
21+
`.github/prompts/design-change.prompt.md`. That flow should stay conversational first: analyze the request, ask
22+
clarifying questions, present design options when needed, and only draft the final scoped solution or GitHub issue after
23+
the discussion is complete.
2324

2425
## Repository map
2526

.github/prompts/design-change.prompt.md

Lines changed: 29 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
Use this prompt with `architect.agent.md` when a change still needs analysis, scoping, and issue drafting before anyone
44
starts editing files.
55

6+
This is a discussion-first prompt. The default behavior is to hold a short design conversation with the user before
7+
producing a final scoped solution, implementation handoff, or GitHub issue draft.
8+
69
## Required inputs
710

811
- The requested change, problem statement, or rough idea
@@ -11,18 +14,36 @@ starts editing files.
1114

1215
## Required process
1316

14-
1. Clarify the real problem first. Ask focused follow-up questions when scope, public-surface impact, or ownership is
15-
unclear.
17+
1. Clarify the real problem first. Ask focused follow-up questions when scope, public-surface impact, ownership, or
18+
rollout direction is unclear.
1619
2. Read `README.md`, `CONTRIBUTING.md`, `.github/instructions/*.md`, and the most relevant `.github/skills/*.md` files.
1720
3. Inspect the affected public command, private helper domain, tests, docs, workflows, or release files without editing
1821
them.
1922
4. Decide whether the request affects public cmdlets, `% nova` CLI behavior, `project.json`, CI/workflows, command
2023
help, website docs, `CHANGELOG.md`, or `RELEASE_NOTE.md`.
21-
5. Recommend the smallest maintainable approach that fits the existing repository structure.
22-
6. End with an implementation-ready handoff and a GitHub issue draft.
23-
7. Do not edit repository files unless the user explicitly switches from design to implementation.
24+
5. Present the user with the clearest trade-offs, options, or design directions when more than one reasonable path
25+
exists.
26+
6. Keep the conversation interactive until the user says the task is clear enough to finalize, or until you explicitly
27+
ask whether you should now draft the final design and GitHub issue.
28+
7. Only after that discussion is complete, produce the final scoped solution, implementation handoff, and GitHub issue
29+
draft.
30+
8. Do not edit repository files unless the user explicitly switches from design to implementation.
31+
32+
## Discussion-phase output
33+
34+
Use the first response and follow-up design turns to drive a conversation, not to dump a finished solution. Prefer:
35+
36+
- a short restatement of the problem
37+
- the most important design questions
38+
- 2-3 concrete solution directions when choices exist
39+
- clear trade-offs
40+
- a recommendation when one option is strongest
41+
42+
Do not produce the full final design package in the first response unless the user explicitly asks for it.
43+
44+
## Finalization output
2445

25-
## Required output
46+
Once the user says the discussion is done, or explicitly asks for the final design, return:
2647

2748
- Problem
2849
- Why it matters
@@ -42,3 +63,5 @@ starts editing files.
4263
- If the final design summary or GitHub issue draft is returned as Markdown or copy-ready UI output, format it according
4364
to `markdown-authoring.skill.md`.
4465
- Draft issue text in English unless the user explicitly asks for another language.
66+
- If the task still has unresolved choices, end the turn with the next best question or the next design decision the
67+
user should make.

CHANGELOG.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1414
- Includes repository instructions, focused agent role definitions, repo-specific skills, and reusable task prompts.
1515
- Aligns the agent guidance with Nova's existing PowerShell, Pester, CodeScene, GitHub Actions, and release
1616
conventions.
17-
- Adds a design-first architect flow so `architect.agent.md` together with `design-change.prompt.md` defaults to
18-
analysis, clarifying questions, and GitHub issue drafting before implementation starts.
17+
- Adds a discussion-first architect flow so `architect.agent.md` together with `design-change.prompt.md` now keeps
18+
the early phase conversational, asks clarifying questions, presents design directions, and only finalizes the
19+
scoped solution and GitHub issue draft after the discussion is complete.
1920
- Includes branch-aware Conventional Commit guidance that derives ticket references from `$GIT_BRANCH_NAME` and
2021
keeps
2122
commit suggestions concise and English-only.

CONTRIBUTING.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,9 @@ Repository-local agentic guidance now lives in `.github/`:
4242
- `.github/skills/` for task-specific repo guidance
4343
- `.github/prompts/` for reusable NovaModuleTools task prompts
4444

45-
When you are shaping a new change, start with `architect.agent.md` and `design-change.prompt.md` so the first outcome is
46-
analysis, clarifying questions, and a GitHub issue draft instead of immediate file edits. Use
47-
`implement-issue.prompt.md` after the change is already scoped.
45+
When you are shaping a new change, start with `architect.agent.md` and `design-change.prompt.md` so the first phase is a
46+
design conversation: analysis, clarifying questions, and solution options before any final scoped proposal or GitHub
47+
issue draft is produced. Use `implement-issue.prompt.md` after the change is already scoped.
4848

4949
Pull requests against `main` and `develop` also run a CodeScene coverage-gate check when CI has produced the Cobertura coverage artifact, so PRs can be blocked when changed code falls below the configured coverage threshold.
5050

README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,8 @@ Repository-local Copilot/AI guidance now lives under:
6262
- `.github/prompts/` - reusable task prompts such as design framing, issue implementation, CI fixes, coverage work, and
6363
release prep
6464

65-
For new or still-fuzzy work, start with `architect.agent.md` together with `design-change.prompt.md`. Use
65+
For new or still-fuzzy work, start with `architect.agent.md` together with `design-change.prompt.md`. That pair should
66+
lead with discussion, questions, and design options rather than a finished solution in the first reply. Use
6667
`implement-issue.prompt.md` once the scope, acceptance criteria, and follow-on implementation path are already clear.
6768

6869
### Prerequisites

0 commit comments

Comments
 (0)