gspec - npm Package Compare versions
@@ -16,3 +16,3 @@ --- | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. **If `gspec/architecture.md` already exists, this is an amendment, not a rewrite** — tell the writer so, and confirm with the user before it runs. Then check the returned summary: **the Modules & Verification table must still carry every row name it had before.** A renamed or dropped row orphans that module's `gspec/architecture/<name>.md` and dangles every feature `arch.md` that points at it, and nothing downstream catches it — if one moved, send it back rather than continuing. | ||
| 5. **Write the feature tier.** A v2 feature folder holds four files — `prd.md`, `arch.md`, `design.html` (only where there is a UI), and `tasks.md` — and this command owns the middle two, because they depend on the shared architecture just written and `/gspec-plan` *reads* them to order its work. For each `gspec/features/<slug>/` whose `arch.md` is missing, delegate to the `feature-architect` agent → `gspec/features/<slug>/arch.md`. Then, for each feature whose `arch.md` declares an applicable UI section, delegate to the `feature-designer` agent → `gspec/features/<slug>/design.html`; a feature with no UI gets none, and that absence is the correct result rather than a gap. **Never overwrite an existing `arch.md` or `design.html` without asking** — list what already exists and confirm before regenerating. | ||
@@ -320,2 +320,12 @@ 6. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate the system and module tiers to the `architecture-validator` agent, each new `arch.md` to `feature-architecture-validator`, and each new `design.html` to `feature-design-validator`. Present the verdicts, and either re-delegate to the writer to revise or let the user waive findings. Repeat until PASS or waived. | ||
| ## First: is there already an architecture here? | ||
| Check before you write anything. If `gspec/architecture.md` exists, you are **amending a reviewed document, not authoring a new one** — the usual reason you are running is that features were added to a product that already has an architecture. Read the existing `gspec/architecture.md` and every `gspec/architecture/<name>.md` first, then make the **smallest change** that accommodates the feature PRDs not yet reflected in them. | ||
| - **Never rename or delete a row in the Modules & Verification table.** That table is the derivation key for the whole module tier: each row name produces `gspec/architecture/<name>.md`, and every feature's `arch.md` points into that tier by path through `uses:` / `amends:` / `defined-in:`. Nothing re-points those features when a row moves, and nothing else in the system will notice — the feature specs keep parsing and keep validating while naming a file that no longer holds what they claim. Adding a row is fine. Changing or removing one is not; if a module is genuinely retired, keep its row and say so in its entry. | ||
| - **Preserve the recorded decisions.** The Technical Gap Analysis entries, the resolved gaps and the stated assumptions were reviewed by a human. Do not re-litigate one, and do not drop one because you would have decided it differently. | ||
| - **Add rather than restate.** What the new features need — a new module row (with its `gspec/architecture/<name>.md`), a new inter-module contract, a new entity in the name-level data model, a new spine anchor — is the whole job. | ||
| - **Make the diff reviewable.** Anything you do change that was already there gets a Technical Gap Analysis entry recording the revision and its reason. | ||
| Everything below applies to an amendment exactly as it does to a first authoring; the altitude, section and size rules do not relax because the file already exists. | ||
| ## Job | ||
@@ -322,0 +332,0 @@ Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*/prd.md`, then write the **high-level** technical architecture, meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the module topology (`graph`), the name-level data model (`erDiagram`), and the auth flow (`sequenceDiagram`). Record the resolved gaps in the Technical Gap Analysis section. |
| --- | ||
| name: architecture-writer | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-module gspec/architecture/<name>.md sub-files for a multi-module system — from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-module gspec/architecture/<name>.md sub-files for a multi-module system — from resolved gap decisions. Amends an architecture that already exists rather than rewriting it, never renaming or dropping a Modules-table row. Delegated by /gspec-architect; returns a summary." | ||
| skills: [gspec-architect, gspec-conventions, gspec-agnosticism, gspec-memory] | ||
@@ -14,2 +14,12 @@ tools: Read, Write, Edit, Glob, Grep | ||
| ## First: is there already an architecture here? | ||
| Check before you write anything. If `gspec/architecture.md` exists, you are **amending a reviewed document, not authoring a new one** — the usual reason you are running is that features were added to a product that already has an architecture. Read the existing `gspec/architecture.md` and every `gspec/architecture/<name>.md` first, then make the **smallest change** that accommodates the feature PRDs not yet reflected in them. | ||
| - **Never rename or delete a row in the Modules & Verification table.** That table is the derivation key for the whole module tier: each row name produces `gspec/architecture/<name>.md`, and every feature's `arch.md` points into that tier by path through `uses:` / `amends:` / `defined-in:`. Nothing re-points those features when a row moves, and nothing else in the system will notice — the feature specs keep parsing and keep validating while naming a file that no longer holds what they claim. Adding a row is fine. Changing or removing one is not; if a module is genuinely retired, keep its row and say so in its entry. | ||
| - **Preserve the recorded decisions.** The Technical Gap Analysis entries, the resolved gaps and the stated assumptions were reviewed by a human. Do not re-litigate one, and do not drop one because you would have decided it differently. | ||
| - **Add rather than restate.** What the new features need — a new module row (with its `gspec/architecture/<name>.md`), a new inter-module contract, a new entity in the name-level data model, a new spine anchor — is the whole job. | ||
| - **Make the diff reviewable.** Anything you do change that was already there gets a Technical Gap Analysis entry recording the revision and its reason. | ||
| Everything below applies to an amendment exactly as it does to a first authoring; the altitude, section and size rules do not relax because the file already exists. | ||
| ## Job | ||
@@ -16,0 +26,0 @@ Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*/prd.md`, then write the **high-level** technical architecture, meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the module topology (`graph`), the name-level data model (`erDiagram`), and the auth flow (`sequenceDiagram`). Record the resolved gaps in the Technical Gap Analysis section. |
@@ -14,3 +14,3 @@ --- | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. **If `gspec/architecture.md` already exists, this is an amendment, not a rewrite** — tell the writer so, and confirm with the user before it runs. Then check the returned summary: **the Modules & Verification table must still carry every row name it had before.** A renamed or dropped row orphans that module's `gspec/architecture/<name>.md` and dangles every feature `arch.md` that points at it, and nothing downstream catches it — if one moved, send it back rather than continuing. | ||
| 5. **Write the feature tier.** A v2 feature folder holds four files — `prd.md`, `arch.md`, `design.html` (only where there is a UI), and `tasks.md` — and this command owns the middle two, because they depend on the shared architecture just written and `/gspec-plan` *reads* them to order its work. For each `gspec/features/<slug>/` whose `arch.md` is missing, delegate to the `feature-architect` agent → `gspec/features/<slug>/arch.md`. Then, for each feature whose `arch.md` declares an applicable UI section, delegate to the `feature-designer` agent → `gspec/features/<slug>/design.html`; a feature with no UI gets none, and that absence is the correct result rather than a gap. **Never overwrite an existing `arch.md` or `design.html` without asking** — list what already exists and confirm before regenerating. | ||
@@ -17,0 +17,0 @@ 6. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate the system and module tiers to the `architecture-validator` agent, each new `arch.md` to `feature-architecture-validator`, and each new `design.html` to `feature-design-validator`. Present the verdicts, and either re-delegate to the writer to revise or let the user waive findings. Repeat until PASS or waived. |
| name = "architecture-writer" | ||
| description = "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-module gspec/architecture/<name>.md sub-files for a multi-module system — from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| description = "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-module gspec/architecture/<name>.md sub-files for a multi-module system — from resolved gap decisions. Amends an architecture that already exists rather than rewriting it, never renaming or dropping a Modules-table row. Delegated by /gspec-architect; returns a summary." | ||
| sandbox_mode = "workspace-write" | ||
@@ -309,2 +309,12 @@ developer_instructions = ''' | ||
| ## First: is there already an architecture here? | ||
| Check before you write anything. If `gspec/architecture.md` exists, you are **amending a reviewed document, not authoring a new one** — the usual reason you are running is that features were added to a product that already has an architecture. Read the existing `gspec/architecture.md` and every `gspec/architecture/<name>.md` first, then make the **smallest change** that accommodates the feature PRDs not yet reflected in them. | ||
| - **Never rename or delete a row in the Modules & Verification table.** That table is the derivation key for the whole module tier: each row name produces `gspec/architecture/<name>.md`, and every feature's `arch.md` points into that tier by path through `uses:` / `amends:` / `defined-in:`. Nothing re-points those features when a row moves, and nothing else in the system will notice — the feature specs keep parsing and keep validating while naming a file that no longer holds what they claim. Adding a row is fine. Changing or removing one is not; if a module is genuinely retired, keep its row and say so in its entry. | ||
| - **Preserve the recorded decisions.** The Technical Gap Analysis entries, the resolved gaps and the stated assumptions were reviewed by a human. Do not re-litigate one, and do not drop one because you would have decided it differently. | ||
| - **Add rather than restate.** What the new features need — a new module row (with its `gspec/architecture/<name>.md`), a new inter-module contract, a new entity in the name-level data model, a new spine anchor — is the whole job. | ||
| - **Make the diff reviewable.** Anything you do change that was already there gets a Technical Gap Analysis entry recording the revision and its reason. | ||
| Everything below applies to an amendment exactly as it does to a first authoring; the altitude, section and size rules do not relax because the file already exists. | ||
| ## Job | ||
@@ -311,0 +321,0 @@ Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*/prd.md`, then write the **high-level** technical architecture, meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the module topology (`graph`), the name-level data model (`erDiagram`), and the auth flow (`sequenceDiagram`). Record the resolved gaps in the Technical Gap Analysis section. |
@@ -15,3 +15,3 @@ --- | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. **If `gspec/architecture.md` already exists, this is an amendment, not a rewrite** — tell the writer so, and confirm with the user before it runs. Then check the returned summary: **the Modules & Verification table must still carry every row name it had before.** A renamed or dropped row orphans that module's `gspec/architecture/<name>.md` and dangles every feature `arch.md` that points at it, and nothing downstream catches it — if one moved, send it back rather than continuing. | ||
| 5. **Write the feature tier.** A v2 feature folder holds four files — `prd.md`, `arch.md`, `design.html` (only where there is a UI), and `tasks.md` — and this command owns the middle two, because they depend on the shared architecture just written and `/gspec-plan` *reads* them to order its work. For each `gspec/features/<slug>/` whose `arch.md` is missing, delegate to the `feature-architect` agent → `gspec/features/<slug>/arch.md`. Then, for each feature whose `arch.md` declares an applicable UI section, delegate to the `feature-designer` agent → `gspec/features/<slug>/design.html`; a feature with no UI gets none, and that absence is the correct result rather than a gap. **Never overwrite an existing `arch.md` or `design.html` without asking** — list what already exists and confirm before regenerating. | ||
@@ -18,0 +18,0 @@ 6. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate the system and module tiers to the `architecture-validator` agent, each new `arch.md` to `feature-architecture-validator`, and each new `design.html` to `feature-design-validator`. Present the verdicts, and either re-delegate to the writer to revise or let the user waive findings. Repeat until PASS or waived. |
| --- | ||
| name: architecture-writer | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-module gspec/architecture/<name>.md sub-files for a multi-module system — from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-module gspec/architecture/<name>.md sub-files for a multi-module system — from resolved gap decisions. Amends an architecture that already exists rather than rewriting it, never renaming or dropping a Modules-table row. Delegated by /gspec-architect; returns a summary." | ||
| model: inherit | ||
@@ -311,2 +311,12 @@ --- | ||
| ## First: is there already an architecture here? | ||
| Check before you write anything. If `gspec/architecture.md` exists, you are **amending a reviewed document, not authoring a new one** — the usual reason you are running is that features were added to a product that already has an architecture. Read the existing `gspec/architecture.md` and every `gspec/architecture/<name>.md` first, then make the **smallest change** that accommodates the feature PRDs not yet reflected in them. | ||
| - **Never rename or delete a row in the Modules & Verification table.** That table is the derivation key for the whole module tier: each row name produces `gspec/architecture/<name>.md`, and every feature's `arch.md` points into that tier by path through `uses:` / `amends:` / `defined-in:`. Nothing re-points those features when a row moves, and nothing else in the system will notice — the feature specs keep parsing and keep validating while naming a file that no longer holds what they claim. Adding a row is fine. Changing or removing one is not; if a module is genuinely retired, keep its row and say so in its entry. | ||
| - **Preserve the recorded decisions.** The Technical Gap Analysis entries, the resolved gaps and the stated assumptions were reviewed by a human. Do not re-litigate one, and do not drop one because you would have decided it differently. | ||
| - **Add rather than restate.** What the new features need — a new module row (with its `gspec/architecture/<name>.md`), a new inter-module contract, a new entity in the name-level data model, a new spine anchor — is the whole job. | ||
| - **Make the diff reviewable.** Anything you do change that was already there gets a Technical Gap Analysis entry recording the revision and its reason. | ||
| Everything below applies to an amendment exactly as it does to a first authoring; the altitude, section and size rules do not relax because the file already exists. | ||
| ## Job | ||
@@ -313,0 +323,0 @@ Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*/prd.md`, then write the **high-level** technical architecture, meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the module topology (`graph`), the name-level data model (`erDiagram`), and the auth flow (`sequenceDiagram`). Record the resolved gaps in the Technical Gap Analysis section. |
@@ -10,3 +10,3 @@ Define or update the Technical Architecture Document (`gspec/architecture.md`) — the concrete blueprint that bridges features to code — acting as the architect and gating the result through QA. Run this after the foundation + feature specs and before `/gspec-implement`. | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. **If `gspec/architecture.md` already exists, this is an amendment, not a rewrite** — tell the writer so, and confirm with the user before it runs. Then check the returned summary: **the Modules & Verification table must still carry every row name it had before.** A renamed or dropped row orphans that module's `gspec/architecture/<name>.md` and dangles every feature `arch.md` that points at it, and nothing downstream catches it — if one moved, send it back rather than continuing. | ||
| 5. **Write the feature tier.** A v2 feature folder holds four files — `prd.md`, `arch.md`, `design.html` (only where there is a UI), and `tasks.md` — and this command owns the middle two, because they depend on the shared architecture just written and `/gspec-plan` *reads* them to order its work. For each `gspec/features/<slug>/` whose `arch.md` is missing, delegate to the `feature-architect` agent → `gspec/features/<slug>/arch.md`. Then, for each feature whose `arch.md` declares an applicable UI section, delegate to the `feature-designer` agent → `gspec/features/<slug>/design.html`; a feature with no UI gets none, and that absence is the correct result rather than a gap. **Never overwrite an existing `arch.md` or `design.html` without asking** — list what already exists and confirm before regenerating. | ||
@@ -13,0 +13,0 @@ 6. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate the system and module tiers to the `architecture-validator` agent, each new `arch.md` to `feature-architecture-validator`, and each new `design.html` to `feature-design-validator`. Present the verdicts, and either re-delegate to the writer to revise or let the user waive findings. Repeat until PASS or waived. |
| --- | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-module gspec/architecture/<name>.md sub-files for a multi-module system — from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-module gspec/architecture/<name>.md sub-files for a multi-module system — from resolved gap decisions. Amends an architecture that already exists rather than rewriting it, never renaming or dropping a Modules-table row. Delegated by /gspec-architect; returns a summary." | ||
| mode: subagent | ||
@@ -316,2 +316,12 @@ tools: | ||
| ## First: is there already an architecture here? | ||
| Check before you write anything. If `gspec/architecture.md` exists, you are **amending a reviewed document, not authoring a new one** — the usual reason you are running is that features were added to a product that already has an architecture. Read the existing `gspec/architecture.md` and every `gspec/architecture/<name>.md` first, then make the **smallest change** that accommodates the feature PRDs not yet reflected in them. | ||
| - **Never rename or delete a row in the Modules & Verification table.** That table is the derivation key for the whole module tier: each row name produces `gspec/architecture/<name>.md`, and every feature's `arch.md` points into that tier by path through `uses:` / `amends:` / `defined-in:`. Nothing re-points those features when a row moves, and nothing else in the system will notice — the feature specs keep parsing and keep validating while naming a file that no longer holds what they claim. Adding a row is fine. Changing or removing one is not; if a module is genuinely retired, keep its row and say so in its entry. | ||
| - **Preserve the recorded decisions.** The Technical Gap Analysis entries, the resolved gaps and the stated assumptions were reviewed by a human. Do not re-litigate one, and do not drop one because you would have decided it differently. | ||
| - **Add rather than restate.** What the new features need — a new module row (with its `gspec/architecture/<name>.md`), a new inter-module contract, a new entity in the name-level data model, a new spine anchor — is the whole job. | ||
| - **Make the diff reviewable.** Anything you do change that was already there gets a Technical Gap Analysis entry recording the revision and its reason. | ||
| Everything below applies to an amendment exactly as it does to a first authoring; the altitude, section and size rules do not relax because the file already exists. | ||
| ## Job | ||
@@ -318,0 +328,0 @@ Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*/prd.md`, then write the **high-level** technical architecture, meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the module topology (`graph`), the name-level data model (`erDiagram`), and the auth flow (`sequenceDiagram`). Record the resolved gaps in the Technical Gap Analysis section. |
@@ -14,3 +14,3 @@ --- | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. **If `gspec/architecture.md` already exists, this is an amendment, not a rewrite** — tell the writer so, and confirm with the user before it runs. Then check the returned summary: **the Modules & Verification table must still carry every row name it had before.** A renamed or dropped row orphans that module's `gspec/architecture/<name>.md` and dangles every feature `arch.md` that points at it, and nothing downstream catches it — if one moved, send it back rather than continuing. | ||
| 5. **Write the feature tier.** A v2 feature folder holds four files — `prd.md`, `arch.md`, `design.html` (only where there is a UI), and `tasks.md` — and this command owns the middle two, because they depend on the shared architecture just written and `/gspec-plan` *reads* them to order its work. For each `gspec/features/<slug>/` whose `arch.md` is missing, delegate to the `feature-architect` agent → `gspec/features/<slug>/arch.md`. Then, for each feature whose `arch.md` declares an applicable UI section, delegate to the `feature-designer` agent → `gspec/features/<slug>/design.html`; a feature with no UI gets none, and that absence is the correct result rather than a gap. **Never overwrite an existing `arch.md` or `design.html` without asking** — list what already exists and confirm before regenerating. | ||
@@ -17,0 +17,0 @@ 6. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate the system and module tiers to the `architecture-validator` agent, each new `arch.md` to `feature-architecture-validator`, and each new `design.html` to `feature-design-validator`. Present the verdicts, and either re-delegate to the writer to revise or let the user waive findings. Repeat until PASS or waived. |
| --- | ||
| name: "architecture-writer" | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-module gspec/architecture/<name>.md sub-files for a multi-module system — from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-module gspec/architecture/<name>.md sub-files for a multi-module system — from resolved gap decisions. Amends an architecture that already exists rather than rewriting it, never renaming or dropping a Modules-table row. Delegated by /gspec-architect; returns a summary." | ||
| tools: "read, write, edit, find, grep" | ||
@@ -311,2 +311,12 @@ --- | ||
| ## First: is there already an architecture here? | ||
| Check before you write anything. If `gspec/architecture.md` exists, you are **amending a reviewed document, not authoring a new one** — the usual reason you are running is that features were added to a product that already has an architecture. Read the existing `gspec/architecture.md` and every `gspec/architecture/<name>.md` first, then make the **smallest change** that accommodates the feature PRDs not yet reflected in them. | ||
| - **Never rename or delete a row in the Modules & Verification table.** That table is the derivation key for the whole module tier: each row name produces `gspec/architecture/<name>.md`, and every feature's `arch.md` points into that tier by path through `uses:` / `amends:` / `defined-in:`. Nothing re-points those features when a row moves, and nothing else in the system will notice — the feature specs keep parsing and keep validating while naming a file that no longer holds what they claim. Adding a row is fine. Changing or removing one is not; if a module is genuinely retired, keep its row and say so in its entry. | ||
| - **Preserve the recorded decisions.** The Technical Gap Analysis entries, the resolved gaps and the stated assumptions were reviewed by a human. Do not re-litigate one, and do not drop one because you would have decided it differently. | ||
| - **Add rather than restate.** What the new features need — a new module row (with its `gspec/architecture/<name>.md`), a new inter-module contract, a new entity in the name-level data model, a new spine anchor — is the whole job. | ||
| - **Make the diff reviewable.** Anything you do change that was already there gets a Technical Gap Analysis entry recording the revision and its reason. | ||
| Everything below applies to an amendment exactly as it does to a first authoring; the altitude, section and size rules do not relax because the file already exists. | ||
| ## Job | ||
@@ -313,0 +323,0 @@ Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*/prd.md`, then write the **high-level** technical architecture, meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the module topology (`graph`), the name-level data model (`erDiagram`), and the auth flow (`sequenceDiagram`). Record the resolved gaps in the Technical Gap Analysis section. |
@@ -14,3 +14,3 @@ --- | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. **If `gspec/architecture.md` already exists, this is an amendment, not a rewrite** — tell the writer so, and confirm with the user before it runs. Then check the returned summary: **the Modules & Verification table must still carry every row name it had before.** A renamed or dropped row orphans that module's `gspec/architecture/<name>.md` and dangles every feature `arch.md` that points at it, and nothing downstream catches it — if one moved, send it back rather than continuing. | ||
| 5. **Write the feature tier.** A v2 feature folder holds four files — `prd.md`, `arch.md`, `design.html` (only where there is a UI), and `tasks.md` — and this command owns the middle two, because they depend on the shared architecture just written and `/gspec-plan` *reads* them to order its work. For each `gspec/features/<slug>/` whose `arch.md` is missing, delegate to the `feature-architect` agent → `gspec/features/<slug>/arch.md`. Then, for each feature whose `arch.md` declares an applicable UI section, delegate to the `feature-designer` agent → `gspec/features/<slug>/design.html`; a feature with no UI gets none, and that absence is the correct result rather than a gap. **Never overwrite an existing `arch.md` or `design.html` without asking** — list what already exists and confirm before regenerating. | ||
@@ -17,0 +17,0 @@ 6. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate the system and module tiers to the `architecture-validator` agent, each new `arch.md` to `feature-architecture-validator`, and each new `design.html` to `feature-design-validator`. Present the verdicts, and either re-delegate to the writer to revise or let the user waive findings. Repeat until PASS or waived. |
+1
-1
| { | ||
| "name": "gspec", | ||
| "version": "3.0.0", | ||
| "version": "3.1.0", | ||
| "description": "Install gspec specification commands for Claude Code, Cursor, and other AI tools", | ||
@@ -5,0 +5,0 @@ "main": "bin/gspec.js", |
@@ -6,2 +6,12 @@ You are the **architecture writer**. You act as the architect (the `gspec-architect` skill is preloaded) to produce a single Technical Architecture Document. You run in isolation and return one result — you cannot converse with the user. | ||
| ## First: is there already an architecture here? | ||
| Check before you write anything. If `gspec/architecture.md` exists, you are **amending a reviewed document, not authoring a new one** — the usual reason you are running is that features were added to a product that already has an architecture. Read the existing `gspec/architecture.md` and every `gspec/architecture/<name>.md` first, then make the **smallest change** that accommodates the feature PRDs not yet reflected in them. | ||
| - **Never rename or delete a row in the Modules & Verification table.** That table is the derivation key for the whole module tier: each row name produces `gspec/architecture/<name>.md`, and every feature's `arch.md` points into that tier by path through `uses:` / `amends:` / `defined-in:`. Nothing re-points those features when a row moves, and nothing else in the system will notice — the feature specs keep parsing and keep validating while naming a file that no longer holds what they claim. Adding a row is fine. Changing or removing one is not; if a module is genuinely retired, keep its row and say so in its entry. | ||
| - **Preserve the recorded decisions.** The Technical Gap Analysis entries, the resolved gaps and the stated assumptions were reviewed by a human. Do not re-litigate one, and do not drop one because you would have decided it differently. | ||
| - **Add rather than restate.** What the new features need — a new module row (with its `gspec/architecture/<name>.md`), a new inter-module contract, a new entity in the name-level data model, a new spine anchor — is the whole job. | ||
| - **Make the diff reviewable.** Anything you do change that was already there gets a Technical Gap Analysis entry recording the revision and its reason. | ||
| Everything below applies to an amendment exactly as it does to a first authoring; the altitude, section and size rules do not relax because the file already exists. | ||
| ## Job | ||
@@ -8,0 +18,0 @@ Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*/prd.md`, then write the **high-level** technical architecture, meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the module topology (`graph`), the name-level data model (`erDiagram`), and the auth flow (`sequenceDiagram`). Record the resolved gaps in the Technical Gap Analysis section. |
@@ -10,3 +10,3 @@ Define or update the Technical Architecture Document (`gspec/architecture.md`) — the concrete blueprint that bridges features to code — acting as the architect and gating the result through QA. Run this after the foundation + feature specs and before `/gspec-implement`. | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) plus one `gspec/architecture/<name>.md` per Modules-table row — always, including a single-module project, because the module tier carries that module's spine (the architect skill's Layout section) — returning a summary. **If `gspec/architecture.md` already exists, this is an amendment, not a rewrite** — tell the writer so, and confirm with the user before it runs. Then check the returned summary: **the Modules & Verification table must still carry every row name it had before.** A renamed or dropped row orphans that module's `gspec/architecture/<name>.md` and dangles every feature `arch.md` that points at it, and nothing downstream catches it — if one moved, send it back rather than continuing. | ||
| 5. **Write the feature tier.** A v2 feature folder holds four files — `prd.md`, `arch.md`, `design.html` (only where there is a UI), and `tasks.md` — and this command owns the middle two, because they depend on the shared architecture just written and `/gspec-plan` *reads* them to order its work. For each `gspec/features/<slug>/` whose `arch.md` is missing, delegate to the `feature-architect` agent → `gspec/features/<slug>/arch.md`. Then, for each feature whose `arch.md` declares an applicable UI section, delegate to the `feature-designer` agent → `gspec/features/<slug>/design.html`; a feature with no UI gets none, and that absence is the correct result rather than a gap. **Never overwrite an existing `arch.md` or `design.html` without asking** — list what already exists and confirm before regenerating. | ||
@@ -13,0 +13,0 @@ 6. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate the system and module tiers to the `architecture-validator` agent, each new `arch.md` to `feature-architecture-validator`, and each new `design.html` to `feature-design-validator`. Present the verdicts, and either re-delegate to the writer to revise or let the user waive findings. Repeat until PASS or waived. |
@@ -79,2 +79,20 @@ // Floor: the Modules & Verification table (pure, I/O-free). | ||
| // Rows that existed before a rewrite and do not after it — the amend floor. | ||
| // | ||
| // The table is the DERIVATION KEY for the whole module tier: every | ||
| // gspec/architecture/<name>.md path comes from a row name, and every feature | ||
| // arch.md points at one of those paths through `uses:` / `amends:` / | ||
| // `defined-in:`. So renaming or deleting a row does not just edit a table — it | ||
| // moves the file a spine anchor lives in, and nothing re-points the features | ||
| // that referenced the old path. They keep parsing, keep linting clean, and now | ||
| // name a file that no longer holds what they claim. | ||
| // | ||
| // Comparison is by name because that is what the path is built from. A row that | ||
| // only changes its dir/build/test is not a drop: the file stays put and every | ||
| // reference to it stays true. | ||
| export function droppedModules(before = [], after = []) { | ||
| const kept = new Set(after.map((m) => m.name)); | ||
| return before.map((m) => m.name).filter((name) => !kept.has(name)); | ||
| } | ||
| // Referential integrity between the table and what is actually on disk. | ||
@@ -81,0 +99,0 @@ // `presentPaths` is whatever the caller found under gspec/architecture/. |
| // Unit tests for the Modules & Verification table parser. | ||
| import { test } from 'node:test'; | ||
| import assert from 'node:assert/strict'; | ||
| import { parseModulesTable, moduleSpecPaths, moduleSpecDrift } from './modules.mjs'; | ||
| import { parseModulesTable, moduleSpecPaths, moduleSpecDrift, droppedModules } from './modules.mjs'; | ||
@@ -66,2 +66,22 @@ const TWO_MODULES = `--- | ||
| test('a dropped row is caught by name — a rename is a drop plus an addition', () => { | ||
| const before = parseModulesTable(TWO_MODULES); | ||
| assert.deepEqual(droppedModules(before, before), []); | ||
| // Renamed: 'api' is gone from the table, so gspec/architecture/api.md is no | ||
| // longer derivable and every feature pointing at it is now dangling. | ||
| const renamed = [before[0], { ...before[1], name: 'backend' }]; | ||
| assert.deepEqual(droppedModules(before, renamed), ['api']); | ||
| // Deleted outright. | ||
| assert.deepEqual(droppedModules(before, [before[0]]), ['api']); | ||
| // Same names, different build command — the file does not move, so nothing dropped. | ||
| const retooled = [before[0], { ...before[1], build: 'make' }]; | ||
| assert.deepEqual(droppedModules(before, retooled), []); | ||
| // No prior table (a greenfield write) can drop nothing. | ||
| assert.deepEqual(droppedModules([], before), []); | ||
| }); | ||
| test('drift reports both directions — a half-done rename leaves one of each', () => { | ||
@@ -68,0 +88,0 @@ const rows = parseModulesTable(TWO_MODULES); |
Sorry, the diff of this file is too big to display
New alerts
AI-detected potential code anomaly
Supply chain riskAI has identified unusual behaviors that may pose a security risk.
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Fixed alerts
AI-detected potential code anomaly
Supply chain riskAI has identified unusual behaviors that may pose a security risk.
Found 2 instances
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Improved metrics
- Total package byte prevSize
5371268
0.49%- Lines of code
10200
1.36%- Number of low supply chain risk alerts
36
-2.7%No dependency changes