@codedrifters/configulator 0.0.216 → 0.0.218
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/index.d.mts +25 -3
- package/lib/index.d.ts +25 -3
- package/lib/index.js +2841 -65
- package/lib/index.js.map +1 -1
- package/lib/index.mjs +2840 -65
- package/lib/index.mjs.map +1 -1
- package/package.json +1 -1
package/lib/index.mjs
CHANGED
|
@@ -4464,7 +4464,7 @@ var orchestratorBundle = {
|
|
|
4464
4464
|
// src/agent/bundles/people-profile.ts
|
|
4465
4465
|
var peopleProfileAnalystSubAgent = {
|
|
4466
4466
|
name: "people-profile-analyst",
|
|
4467
|
-
description: "Researches an individual person (colleague, customer contact, vendor contact, partner contact, industry expert, or connector) from public sources and produces a structured markdown profile cross-linked to companies, software, and meeting notes. One person per session, tracked by people:* GitHub issue labels.",
|
|
4467
|
+
description: "Researches an individual person (colleague, customer contact, vendor contact, partner contact, industry expert, or connector) from public sources and produces a structured markdown profile cross-linked to companies, software, and meeting notes, then enqueues downstream `company:research` and `software:research` issues for unprofiled companies and software products surfaced during profiling. One person per session, tracked by people:* GitHub issue labels.",
|
|
4468
4468
|
model: AGENT_MODEL.POWERFUL,
|
|
4469
4469
|
maxTurns: 80,
|
|
4470
4470
|
platforms: { cursor: { exclude: true } },
|
|
@@ -4514,8 +4514,16 @@ var peopleProfileAnalystSubAgent = {
|
|
|
4514
4514
|
"7. **Cross-reference, don't duplicate.** When the profile mentions a",
|
|
4515
4515
|
" company, software product, or meeting already tracked by the",
|
|
4516
4516
|
" consuming project, link to the existing artifact rather than",
|
|
4517
|
-
" duplicating its content.
|
|
4518
|
-
"
|
|
4517
|
+
" duplicating its content.",
|
|
4518
|
+
"8. **Follow-up, don't widen scope.** If the session turns up adjacent",
|
|
4519
|
+
" research questions (a significant employer worth profiling, a",
|
|
4520
|
+
" software product the person created or leads), emit a follow-up",
|
|
4521
|
+
" issue rather than expanding the profile beyond its scope.",
|
|
4522
|
+
" Companies are handed off to the `company-profile` bundle via",
|
|
4523
|
+
" `company:research` issues; software products are handed off to",
|
|
4524
|
+
" the `software-profile` bundle via `software:research` issues.",
|
|
4525
|
+
" Meeting notes remain link-only \u2014 this agent never creates",
|
|
4526
|
+
" meeting-research issues.",
|
|
4519
4527
|
"",
|
|
4520
4528
|
"---",
|
|
4521
4529
|
"",
|
|
@@ -4543,13 +4551,13 @@ var peopleProfileAnalystSubAgent = {
|
|
|
4543
4551
|
"## State Machine Overview",
|
|
4544
4552
|
"",
|
|
4545
4553
|
"```",
|
|
4546
|
-
"\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
|
|
4547
|
-
"\u2502 1. RESEARCH \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 2. DRAFT PROFILE \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 3. FOLLOWUP
|
|
4548
|
-
"\u2502 Collect public \u2502 \u2502 Write the structured \u2502 \u2502 Cross-link
|
|
4549
|
-
"\u2502 sources into a \u2502 \u2502 markdown profile to \u2502 \u2502
|
|
4550
|
-
"\u2502 bounded notes \u2502 \u2502 the configured path \u2502 \u2502
|
|
4551
|
-
"\u2502 file \u2502 \u2502 \u2502 \u2502
|
|
4552
|
-
"\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
|
|
4554
|
+
"\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
|
|
4555
|
+
"\u2502 1. RESEARCH \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 2. DRAFT PROFILE \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 3. FOLLOWUP \u2502",
|
|
4556
|
+
"\u2502 Collect public \u2502 \u2502 Write the structured \u2502 \u2502 Cross-link existing\u2502",
|
|
4557
|
+
"\u2502 sources into a \u2502 \u2502 markdown profile to \u2502 \u2502 artifacts; enqueue \u2502",
|
|
4558
|
+
"\u2502 bounded notes \u2502 \u2502 the configured path \u2502 \u2502 company/software \u2502",
|
|
4559
|
+
"\u2502 file \u2502 \u2502 \u2502 \u2502 research issues \u2502",
|
|
4560
|
+
"\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
|
|
4553
4561
|
"```",
|
|
4554
4562
|
"",
|
|
4555
4563
|
"**Issue labels encode the phase:**",
|
|
@@ -4558,19 +4566,21 @@ var peopleProfileAnalystSubAgent = {
|
|
|
4558
4566
|
"|-------|-------|-------------|",
|
|
4559
4567
|
"| `people:research` | 1. Research | Gather public sources. Write a bounded research-notes file. Create the draft issue. |",
|
|
4560
4568
|
"| `people:draft` | 2. Draft | Read the research notes. Write the structured profile to `<PROFILES_DIR>`. Create the followup issue if warranted. |",
|
|
4561
|
-
"| `people:followup` | 3. Followup | Read the profile. Update cross-references to existing companies, software, and meeting notes.
|
|
4569
|
+
"| `people:followup` | 3. Followup | Read the profile. Update cross-references to existing companies, software, and meeting notes. Enqueue `company:research` and `software:research` issues for unprofiled, genuinely-relevant entities surfaced in the profile. |",
|
|
4562
4570
|
"",
|
|
4563
4571
|
"All issues also carry `type:people-profile` and a `status:*` label.",
|
|
4564
4572
|
"",
|
|
4565
4573
|
"**Issue count per person cycle:** 1 research + 1 draft + 0\u20131 followup =",
|
|
4566
4574
|
"**2\u20133 sessions**. The followup phase is skipped when the profile did",
|
|
4567
|
-
"not surface any cross-references worth linking
|
|
4575
|
+
"not surface any cross-references worth linking and no companies or",
|
|
4576
|
+
"software products warrant downstream research.",
|
|
4568
4577
|
"",
|
|
4569
4578
|
"**Shortened paths:**",
|
|
4570
4579
|
"- Research phase determines the person is out of scope (not",
|
|
4571
4580
|
" relevant, insufficient public material) \u2192 research issue closes",
|
|
4572
4581
|
" with a justification and no downstream issues are created \u2192 **1 session**.",
|
|
4573
|
-
"- Short profile with no cross-references
|
|
4582
|
+
"- Short profile with no cross-references and no downstream",
|
|
4583
|
+
" candidates \u2192 **2 sessions**.",
|
|
4574
4584
|
"",
|
|
4575
4585
|
"---",
|
|
4576
4586
|
"",
|
|
@@ -4586,8 +4596,8 @@ var peopleProfileAnalystSubAgent = {
|
|
|
4586
4596
|
"| `<PROFILES_DIR>` | Final person profile files | `<PEOPLE_ROOT>/profiles/` |",
|
|
4587
4597
|
"| `<NOTES_DIR>` | Research-notes files from Phase 1 | `<PEOPLE_ROOT>/notes/` |",
|
|
4588
4598
|
"| `<PERSON_SLUG>` | Short kebab-case slug identifying the person | derived from the person's name |",
|
|
4589
|
-
"| `<COMPANIES_DIR>` | Where existing company profiles live (for cross-references) | `docs/companies/profiles/` |",
|
|
4590
|
-
"| `<SOFTWARE_DIR>` | Where existing software profiles live (for cross-references) | `docs/software/profiles/` |",
|
|
4599
|
+
"| `<COMPANIES_DIR>` | Where existing company profiles live (for cross-references and duplicate detection during followup) | `docs/companies/profiles/` |",
|
|
4600
|
+
"| `<SOFTWARE_DIR>` | Where existing software profiles live (for cross-references and duplicate detection during followup) | `docs/software/profiles/` |",
|
|
4591
4601
|
"| `<MEETINGS_DIR>` | Where meeting notes live (for cross-references) | `docs/meetings/` |",
|
|
4592
4602
|
"",
|
|
4593
4603
|
"If `docs/project-context.md` specifies a different people-research",
|
|
@@ -4801,11 +4811,13 @@ var peopleProfileAnalystSubAgent = {
|
|
|
4801
4811
|
" ```",
|
|
4802
4812
|
"",
|
|
4803
4813
|
"4. **Decide whether a followup issue is warranted.** Create a",
|
|
4804
|
-
" `people:followup` issue (depending on this draft issue)
|
|
4805
|
-
"
|
|
4806
|
-
"
|
|
4807
|
-
"
|
|
4808
|
-
"
|
|
4814
|
+
" `people:followup` issue (depending on this draft issue) if the",
|
|
4815
|
+
" profile's Candidate Cross-References lists at least one company,",
|
|
4816
|
+
" software product, or meeting \u2014 whether or not the entity is",
|
|
4817
|
+
" already profiled. The followup phase links what exists and",
|
|
4818
|
+
" enqueues downstream research for what doesn't. Only skip the",
|
|
4819
|
+
" followup when the profile surfaced no cross-reference candidates",
|
|
4820
|
+
" at all; note this in the draft issue's closing comment.",
|
|
4809
4821
|
"",
|
|
4810
4822
|
"5. **Commit and push** the profile file. Close the draft issue.",
|
|
4811
4823
|
"",
|
|
@@ -4815,11 +4827,17 @@ var peopleProfileAnalystSubAgent = {
|
|
|
4815
4827
|
"",
|
|
4816
4828
|
"**Goal:** Populate the profile's `## Cross-References` section with",
|
|
4817
4829
|
"links to existing artifacts \u2014 companies, software, meetings \u2014 that",
|
|
4818
|
-
"the consuming project already tracks
|
|
4819
|
-
"",
|
|
4820
|
-
"
|
|
4821
|
-
"
|
|
4822
|
-
"
|
|
4830
|
+
"the consuming project already tracks, **and** enqueue downstream",
|
|
4831
|
+
"`company:research` and `software:research` issues for unprofiled,",
|
|
4832
|
+
"genuinely-relevant companies and software products surfaced in the",
|
|
4833
|
+
"profile. Hand the candidates off to the `company-profile` and",
|
|
4834
|
+
"`software-profile` bundles so they can be researched independently.",
|
|
4835
|
+
"",
|
|
4836
|
+
"**Budget:** No new web searches. Read the candidate cross-references,",
|
|
4837
|
+
"resolve them against the configured directories, update the profile,",
|
|
4838
|
+
"and enqueue downstream research issues where warranted. Markdown",
|
|
4839
|
+
"cross-references in the profile are preserved \u2014 issue creation is",
|
|
4840
|
+
"**additive** on top of the existing cross-reference behavior.",
|
|
4823
4841
|
"",
|
|
4824
4842
|
"### Steps",
|
|
4825
4843
|
"",
|
|
@@ -4828,24 +4846,108 @@ var peopleProfileAnalystSubAgent = {
|
|
|
4828
4846
|
"2. **Resolve company cross-references.** For each company named in",
|
|
4829
4847
|
" the profile's research notes or body text, look for a matching",
|
|
4830
4848
|
" file under `<COMPANIES_DIR>/`. If found, link it under",
|
|
4831
|
-
" `## Cross-References > Companies
|
|
4832
|
-
"
|
|
4833
|
-
" whether to kick off a separate company-profile pipeline.",
|
|
4849
|
+
" `## Cross-References > Companies` and do **not** open a",
|
|
4850
|
+
" `company:research` issue for it \u2014 the profile already exists.",
|
|
4834
4851
|
"",
|
|
4835
4852
|
"3. **Resolve software cross-references.** Same pattern against",
|
|
4836
|
-
" `<SOFTWARE_DIR>/`.
|
|
4837
|
-
"
|
|
4853
|
+
" `<SOFTWARE_DIR>/`. If found, link under `## Cross-References >",
|
|
4854
|
+
" Software` and do **not** open a `software:research` issue.",
|
|
4838
4855
|
"",
|
|
4839
4856
|
"4. **Resolve meeting cross-references.** For meetings the person",
|
|
4840
4857
|
" participated in, look for a matching file under `<MEETINGS_DIR>/`",
|
|
4841
|
-
" by date or slug. Link matches; leave TODOs otherwise.",
|
|
4858
|
+
" by date or slug. Link matches; leave TODOs otherwise. Meeting",
|
|
4859
|
+
" notes are **always link-only** \u2014 this agent never opens",
|
|
4860
|
+
" meeting-research issues.",
|
|
4861
|
+
"",
|
|
4862
|
+
"5. **Enqueue a `company:research` issue per unprofiled, genuinely-",
|
|
4863
|
+
" relevant company.** For each company named in the profile that",
|
|
4864
|
+
" has no matching file under `<COMPANIES_DIR>/`, decide whether it",
|
|
4865
|
+
" warrants a downstream company profile (see restraint guidance",
|
|
4866
|
+
" below). If so, open an issue carrying:",
|
|
4867
|
+
"",
|
|
4868
|
+
" - `type:company-profile`",
|
|
4869
|
+
" - `company:research`",
|
|
4870
|
+
" - `priority:medium`",
|
|
4871
|
+
" - `status:ready`",
|
|
4872
|
+
"",
|
|
4873
|
+
" The issue body must include:",
|
|
4874
|
+
" - A **discovery source** line naming this person profile",
|
|
4875
|
+
" (`Discovered while profiling: <person name>`)",
|
|
4876
|
+
" - A link to the person profile path (`Person profile: <PROFILES_DIR>/<PERSON_SLUG>.md`)",
|
|
4877
|
+
" - Enough identifying metadata \u2014 company name and primary domain/",
|
|
4878
|
+
" website \u2014 that the `company-profile-analyst` agent can begin",
|
|
4879
|
+
" research without revisiting this person profile",
|
|
4880
|
+
"",
|
|
4881
|
+
"6. **Enqueue a `software:research` issue per unprofiled software",
|
|
4882
|
+
" product the person has primary attribution for.** For each",
|
|
4883
|
+
" software product named in the profile with no matching file under",
|
|
4884
|
+
" `<SOFTWARE_DIR>/`, decide whether it warrants a downstream",
|
|
4885
|
+
" software profile (see restraint guidance below). If so, open an",
|
|
4886
|
+
" issue carrying:",
|
|
4842
4887
|
"",
|
|
4843
|
-
"
|
|
4844
|
-
" `
|
|
4845
|
-
"
|
|
4846
|
-
"
|
|
4888
|
+
" - `type:software-profile`",
|
|
4889
|
+
" - `software:research`",
|
|
4890
|
+
" - `priority:medium`",
|
|
4891
|
+
" - `status:ready`",
|
|
4847
4892
|
"",
|
|
4848
|
-
"
|
|
4893
|
+
" The issue body must include:",
|
|
4894
|
+
" - A **discovery source** line naming this person profile",
|
|
4895
|
+
" (`Discovered while profiling: <person name>`)",
|
|
4896
|
+
" - A link to the person profile path (`Person profile: <PROFILES_DIR>/<PERSON_SLUG>.md`)",
|
|
4897
|
+
" - Enough identifying metadata \u2014 product name and vendor (the",
|
|
4898
|
+
" company that builds or maintains the product) \u2014 that the",
|
|
4899
|
+
" `software-profile-analyst` agent can begin research without",
|
|
4900
|
+
" revisiting this person profile",
|
|
4901
|
+
"",
|
|
4902
|
+
"7. **Avoid duplicates.** Before opening a `company:research` or",
|
|
4903
|
+
" `software:research` issue, verify no existing profile or open",
|
|
4904
|
+
" research issue already covers the candidate:",
|
|
4905
|
+
"",
|
|
4906
|
+
" - Companies: check `<COMPANIES_DIR>/` for a matching profile",
|
|
4907
|
+
" file (by derived slug or by searching the directory for the",
|
|
4908
|
+
" company's name). If a profile exists, reuse it as a cross-",
|
|
4909
|
+
" reference only \u2014 **do not** open a new `company:research` issue.",
|
|
4910
|
+
" - Software: check `<SOFTWARE_DIR>/` the same way. If a profile",
|
|
4911
|
+
" exists, reuse it as a cross-reference only \u2014 **do not** open a",
|
|
4912
|
+
" new `software:research` issue.",
|
|
4913
|
+
" - Also scan open issues carrying the matching `company:research`",
|
|
4914
|
+
" or `software:research` label so this phase never re-opens",
|
|
4915
|
+
" research that is already queued.",
|
|
4916
|
+
"",
|
|
4917
|
+
"8. **Exercise restraint.** Only create downstream issues for",
|
|
4918
|
+
" entities **genuinely relevant** to the person's professional",
|
|
4919
|
+
" identity:",
|
|
4920
|
+
"",
|
|
4921
|
+
" - **Companies:** open an issue for the person's current",
|
|
4922
|
+
" employer, significant past employers (roles of real tenure or",
|
|
4923
|
+
" leadership influence), companies where they sit on the board",
|
|
4924
|
+
" or act as an advisor, and companies they co-founded. Do **not**",
|
|
4925
|
+
" open an issue for every company on their LinkedIn, short",
|
|
4926
|
+
" consulting engagements, or employers tangential to the framing",
|
|
4927
|
+
" of this profile.",
|
|
4928
|
+
" - **Software:** open an issue only for products where the person",
|
|
4929
|
+
" has **primary attribution** \u2014 creator, maintainer, lead PM,",
|
|
4930
|
+
" founding engineer, or otherwise materially influenced the",
|
|
4931
|
+
" product. Do **not** open an issue for software the person",
|
|
4932
|
+
" merely uses, endorses in passing, or lists in a stack. When",
|
|
4933
|
+
" in doubt, leave the candidate as a markdown cross-reference",
|
|
4934
|
+
" and skip the downstream issue.",
|
|
4935
|
+
"",
|
|
4936
|
+
"9. **Assume the peers are present.** This pipeline assumes the",
|
|
4937
|
+
" `company-profile` and `software-profile` bundles are enabled in",
|
|
4938
|
+
" the consuming project. If a consuming project has disabled one",
|
|
4939
|
+
" of them, flag the followup issue with `status:needs-attention`",
|
|
4940
|
+
" and list the candidates that could not be routed \u2014 never invent",
|
|
4941
|
+
" an alternative label taxonomy.",
|
|
4942
|
+
"",
|
|
4943
|
+
"10. **Cross-link** \u2014 update the profile's `## Cross-References`",
|
|
4944
|
+
" section so each company or software entry references either",
|
|
4945
|
+
" the linked profile path (for existing profiles) or the newly-",
|
|
4946
|
+
" created downstream issue number (for candidates that were",
|
|
4947
|
+
" enqueued for research).",
|
|
4948
|
+
"",
|
|
4949
|
+
"11. **Commit and push** the updated profile. Close the followup",
|
|
4950
|
+
" issue.",
|
|
4849
4951
|
"",
|
|
4850
4952
|
"---",
|
|
4851
4953
|
"",
|
|
@@ -4856,12 +4958,22 @@ var peopleProfileAnalystSubAgent = {
|
|
|
4856
4958
|
"- `<NOTES_DIR>/` \u2014 research-notes files (Phase 1)",
|
|
4857
4959
|
"- `<PROFILES_DIR>/` \u2014 person profiles (Phase 2, updated in Phase 3)",
|
|
4858
4960
|
"",
|
|
4859
|
-
"
|
|
4860
|
-
"
|
|
4861
|
-
"
|
|
4862
|
-
"
|
|
4863
|
-
"
|
|
4864
|
-
"
|
|
4961
|
+
"In Phase 3, this agent also **creates `company:research` and",
|
|
4962
|
+
"`software:research` issues** for companies and software products",
|
|
4963
|
+
"surfaced in the profile that are not already tracked under",
|
|
4964
|
+
"`<COMPANIES_DIR>/` or `<SOFTWARE_DIR>/`. It never writes the",
|
|
4965
|
+
"downstream profiles themselves \u2014 those are the responsibility of the",
|
|
4966
|
+
"`company-profile-analyst` and `software-profile-analyst` agents,",
|
|
4967
|
+
"which pick up the issues this pipeline creates. Meeting notes",
|
|
4968
|
+
"remain link-only across all phases.",
|
|
4969
|
+
"",
|
|
4970
|
+
"The pipeline produces **person profiles and notes only**. Deeper",
|
|
4971
|
+
"research on companies and software products is delegated to",
|
|
4972
|
+
"downstream research pipelines via `company:research` and",
|
|
4973
|
+
"`software:research` issues \u2014 this agent never writes company",
|
|
4974
|
+
"profiles, software profiles, product evaluations, or comparative",
|
|
4975
|
+
"analyses itself. Keep this boundary clean so the people-profile",
|
|
4976
|
+
"pipeline stays generic.",
|
|
4865
4977
|
"",
|
|
4866
4978
|
"---",
|
|
4867
4979
|
"",
|
|
@@ -4877,15 +4989,35 @@ var peopleProfileAnalystSubAgent = {
|
|
|
4877
4989
|
" encountered in a public source.",
|
|
4878
4990
|
"- **Cross-reference, don't duplicate.** Link to existing company,",
|
|
4879
4991
|
" software, and meeting artifacts rather than re-describing them.",
|
|
4880
|
-
"- **
|
|
4881
|
-
"
|
|
4992
|
+
"- **Delegate, don't duplicate.** Unprofiled companies and software",
|
|
4993
|
+
" products surfaced during profiling are handed off to the",
|
|
4994
|
+
" `company-profile` and `software-profile` bundles via",
|
|
4995
|
+
" `company:research` and `software:research` issues in Phase 3 \u2014",
|
|
4996
|
+
" never inlined as company or software profiles in this pipeline.",
|
|
4997
|
+
"- **Check before enqueueing.** Before opening a `company:research`",
|
|
4998
|
+
" or `software:research` issue, verify no existing profile or open",
|
|
4999
|
+
" research issue already covers the candidate. Reuse existing",
|
|
5000
|
+
" profiles as cross-references rather than re-queuing research.",
|
|
5001
|
+
"- **Restrain the queue.** Only enqueue downstream research for",
|
|
5002
|
+
" companies that are a current employer, significant past employer,",
|
|
5003
|
+
" board/advisor role, or co-founded venture \u2014 not every company on",
|
|
5004
|
+
" the person's r\xE9sum\xE9. Only enqueue software research for products",
|
|
5005
|
+
" the person has **primary attribution** for (creator, maintainer,",
|
|
5006
|
+
" lead PM), not products they merely use.",
|
|
5007
|
+
"- **Meetings stay link-only.** Phase 3 never opens meeting-research",
|
|
5008
|
+
" or any other meeting-related issues. Meetings are cross-",
|
|
5009
|
+
" referenced only.",
|
|
5010
|
+
"- **Produce profiles, not requirement or evaluation documents.** Do",
|
|
5011
|
+
" not open `type:requirement` or formal evaluation issues from this",
|
|
5012
|
+
" pipeline. Follow-up research is scoped through `company:research`",
|
|
5013
|
+
" and `software:research` only.",
|
|
4882
5014
|
"- **Refresh, don't fork.** When a profile exists and is past its",
|
|
4883
5015
|
" cadence, update in place rather than creating a new slug."
|
|
4884
5016
|
].join("\n")
|
|
4885
5017
|
};
|
|
4886
5018
|
var profilePersonSkill = {
|
|
4887
5019
|
name: "profile-person",
|
|
4888
|
-
description: "Kick off a people-profile pipeline. Creates a people:research issue for the given person and dispatches Phase 1 (Research) in the people-profile-analyst agent.",
|
|
5020
|
+
description: "Kick off a people-profile pipeline. Creates a people:research issue for the given person and dispatches Phase 1 (Research) in the people-profile-analyst agent. Phase 3 (Followup) enqueues downstream `company:research` and `software:research` issues for unprofiled, genuinely-relevant entities surfaced in the profile.",
|
|
4889
5021
|
disableModelInvocation: true,
|
|
4890
5022
|
userInvocable: true,
|
|
4891
5023
|
context: "fork",
|
|
@@ -4947,13 +5079,19 @@ var profilePersonSkill = {
|
|
|
4947
5079
|
"- A single person profile under the profiles directory",
|
|
4948
5080
|
"- Cross-references to existing companies, software, and meetings",
|
|
4949
5081
|
" tracked elsewhere in the project",
|
|
4950
|
-
"-
|
|
4951
|
-
"
|
|
5082
|
+
"- `company:research` issues for unprofiled companies surfaced in",
|
|
5083
|
+
" the profile (handed off to the `company-profile` bundle)",
|
|
5084
|
+
"- `software:research` issues for software products the person has",
|
|
5085
|
+
" primary attribution for (handed off to the `software-profile`",
|
|
5086
|
+
" bundle)",
|
|
5087
|
+
"- This pipeline produces **person profiles only** \u2014 it does not",
|
|
5088
|
+
" write company profiles, software profiles, meeting notes, or any",
|
|
5089
|
+
" other downstream artifacts itself."
|
|
4952
5090
|
].join("\n")
|
|
4953
5091
|
};
|
|
4954
5092
|
var peopleProfileBundle = {
|
|
4955
5093
|
name: "people-profile",
|
|
4956
|
-
description: "People research and profiling pipeline: research, draft profile, followup. Enabled by default; domain-neutral; filesystem-durable between phases
|
|
5094
|
+
description: "People research and profiling pipeline: research, draft profile, followup. Enabled by default; domain-neutral; filesystem-durable between phases. Cross-references existing companies, software, and meeting notes, and Phase 3 (Followup) hands unprofiled, genuinely-relevant companies and software products off to the `company-profile` and `software-profile` bundles via `company:research` and `software:research` issues.",
|
|
4957
5095
|
appliesWhen: () => true,
|
|
4958
5096
|
rules: [
|
|
4959
5097
|
{
|
|
@@ -4969,10 +5107,12 @@ var peopleProfileBundle = {
|
|
|
4969
5107
|
"GitHub issue labeled `people:research`, `people:draft`, or",
|
|
4970
5108
|
"`people:followup`. All issues carry `type:people-profile`.",
|
|
4971
5109
|
"",
|
|
4972
|
-
"The pipeline produces **person profiles only**.
|
|
4973
|
-
"
|
|
4974
|
-
"
|
|
4975
|
-
"
|
|
5110
|
+
"The pipeline produces **person profiles only**. Deeper research",
|
|
5111
|
+
"on companies and software products surfaced while profiling is",
|
|
5112
|
+
"delegated to the `company-profile` and `software-profile`",
|
|
5113
|
+
"bundles via `company:research` and `software:research` issues",
|
|
5114
|
+
"opened during Phase 3 (Followup). Meeting notes remain link-",
|
|
5115
|
+
"only \u2014 the pipeline never creates meeting-research issues.",
|
|
4976
5116
|
"",
|
|
4977
5117
|
"See the `people-profile-analyst` agent definition for full",
|
|
4978
5118
|
"workflow details, default paths, the person-role taxonomy, the",
|
|
@@ -5005,7 +5145,7 @@ var peopleProfileBundle = {
|
|
|
5005
5145
|
{
|
|
5006
5146
|
name: "people:followup",
|
|
5007
5147
|
color: "D4C5F9",
|
|
5008
|
-
description: "Phase 3: cross-link the profile to existing companies, software, and meeting notes"
|
|
5148
|
+
description: "Phase 3: cross-link the profile to existing companies, software, and meeting notes, and enqueue follow-up research issues for unprofiled companies and software products"
|
|
5009
5149
|
}
|
|
5010
5150
|
]
|
|
5011
5151
|
};
|
|
@@ -5811,8 +5951,8 @@ var requirementsAnalystSubAgent = {
|
|
|
5811
5951
|
"Dedicated agent loop for discovering requirement gaps from BCM (Business",
|
|
5812
5952
|
"Capability Model) documents, product docs, and competitive analysis \u2014 then",
|
|
5813
5953
|
"creating well-formed requirement issues for the downstream",
|
|
5814
|
-
"requirements-writer
|
|
5815
|
-
"
|
|
5954
|
+
"`requirements-writer` agent to draft. Designed for scheduled execution",
|
|
5955
|
+
"downstream of the BCM writer and company research agents.",
|
|
5816
5956
|
"",
|
|
5817
5957
|
"Follow your project's shared agent conventions (`AGENTS.md`,",
|
|
5818
5958
|
"`CLAUDE.md`, or equivalent) for all commit, branch, and PR rules.",
|
|
@@ -5823,8 +5963,9 @@ var requirementsAnalystSubAgent = {
|
|
|
5823
5963
|
"## Design Principles",
|
|
5824
5964
|
"",
|
|
5825
5965
|
"1. **Discover, don't write.** This agent identifies *what requirements are",
|
|
5826
|
-
" missing*. The requirements-writer
|
|
5827
|
-
" boundary keeps this agent fast and the requirements-writer
|
|
5966
|
+
" missing*. The `requirements-writer` agent writes the actual documents.",
|
|
5967
|
+
" The boundary keeps this agent fast and the `requirements-writer`",
|
|
5968
|
+
" authoritative.",
|
|
5828
5969
|
"2. **Trace everything.** Every discovered gap links to the source that",
|
|
5829
5970
|
" revealed it (a BCM model doc, competitive analysis, product doc, or",
|
|
5830
5971
|
" meeting extract).",
|
|
@@ -6082,12 +6223,14 @@ var requirementsAnalystSubAgent = {
|
|
|
6082
6223
|
"2. **Create requirement issues.** For each proposal:",
|
|
6083
6224
|
"",
|
|
6084
6225
|
" All `type:requirement` issues default to `priority:medium` (override",
|
|
6085
|
-
" only if the proposal's priority was explicitly High or Low).",
|
|
6226
|
+
" only if the proposal's priority was explicitly High or Low). Each",
|
|
6227
|
+
" issue must also carry the `req:write` phase label so the downstream",
|
|
6228
|
+
" `requirements-writer` bundle picks it up.",
|
|
6086
6229
|
"",
|
|
6087
6230
|
" ```bash",
|
|
6088
6231
|
" gh issue create \\",
|
|
6089
6232
|
' --title "docs(<category>): <PREFIX>-<NNN> \u2014 <title>" \\',
|
|
6090
|
-
' --label "type:requirement" --label "status:ready" --label "priority:medium" \\',
|
|
6233
|
+
' --label "type:requirement" --label "req:write" --label "status:ready" --label "priority:medium" \\',
|
|
6091
6234
|
' --body "## Objective',
|
|
6092
6235
|
" Write <PREFIX>-<NNN> \u2014 <title>.",
|
|
6093
6236
|
"",
|
|
@@ -6136,7 +6279,7 @@ var requirementsAnalystSubAgent = {
|
|
|
6136
6279
|
"| Upstream | BCM Writer | Scans capability-model docs for project-relevance gaps (judged against `docs/project-context.md`) |",
|
|
6137
6280
|
"| Upstream | Company Research | Scans competitive analysis for feature comparison gaps |",
|
|
6138
6281
|
"| Upstream | Meeting Analyst | Scans meeting extracts for requirement proposals |",
|
|
6139
|
-
"| Downstream |
|
|
6282
|
+
"| Downstream | `requirements-writer` | Picks up the `type:requirement` + `req:write` issues this agent creates and drafts the actual requirement document |",
|
|
6140
6283
|
"",
|
|
6141
6284
|
"**File boundaries:** Writes to `<RESEARCH_REQUIREMENTS_ROOT>/req-*.md` and",
|
|
6142
6285
|
"minor traceability edits to `<BCM_DOCS_ROOT>` and `<COMPETITIVE_ROOT>`.",
|
|
@@ -6157,7 +6300,8 @@ var requirementsAnalystSubAgent = {
|
|
|
6157
6300
|
"## Rules",
|
|
6158
6301
|
"",
|
|
6159
6302
|
"- **Discover, don't write requirements.** Create issues for the",
|
|
6160
|
-
" requirements-writer \u2014 don't write requirement documents
|
|
6303
|
+
" `requirements-writer` agent \u2014 don't write requirement documents",
|
|
6304
|
+
" directly.",
|
|
6161
6305
|
"- **Deduplicate rigorously.** Check both existing docs and open issues",
|
|
6162
6306
|
" before flagging a gap.",
|
|
6163
6307
|
"- **Respect decision authority.** Mark ADR/TR proposals as needing human",
|
|
@@ -6229,10 +6373,12 @@ var requirementsAnalystBundle = {
|
|
|
6229
6373
|
"or `req:trace`. All issues carry `type:requirement`.",
|
|
6230
6374
|
"",
|
|
6231
6375
|
"The requirements-analyst *discovers gaps and drafts proposals*; it",
|
|
6232
|
-
"does **not** write final requirement documents. Writing is the job
|
|
6233
|
-
"the downstream requirements-writer (
|
|
6234
|
-
"boundary clean: proposals land under the research
|
|
6235
|
-
"directory, not under the authoritative requirements
|
|
6376
|
+
"does **not** write final requirement documents. Writing is the job",
|
|
6377
|
+
"of the downstream `requirements-writer` agent (a separate bundle).",
|
|
6378
|
+
"Keep that boundary clean: proposals land under the research",
|
|
6379
|
+
"requirements directory, not under the authoritative requirements",
|
|
6380
|
+
"tree. The trace phase tags new issues with `req:write` so the",
|
|
6381
|
+
"writer bundle picks them up automatically.",
|
|
6236
6382
|
"",
|
|
6237
6383
|
"See the `requirements-analyst` agent definition for full workflow",
|
|
6238
6384
|
"details and phase-by-phase instructions."
|
|
@@ -6269,6 +6415,2633 @@ var requirementsAnalystBundle = {
|
|
|
6269
6415
|
]
|
|
6270
6416
|
};
|
|
6271
6417
|
|
|
6418
|
+
// src/agent/bundles/requirements-writer.ts
|
|
6419
|
+
var TEMPLATE_BR = `---
|
|
6420
|
+
title: "BR-NNN: [Business Requirement Title]"
|
|
6421
|
+
---
|
|
6422
|
+
|
|
6423
|
+
# BR-NNN: [Business Requirement Title]
|
|
6424
|
+
|
|
6425
|
+
## Metadata
|
|
6426
|
+
|
|
6427
|
+
| Field | Value |
|
|
6428
|
+
|---|---|
|
|
6429
|
+
| **ID** | BR-NNN |
|
|
6430
|
+
| **Status** | Draft |
|
|
6431
|
+
| **Tier** | [Platform \xB7 Industry \xB7 Customer Workflow \xB7 Consumer Application] |
|
|
6432
|
+
| **Implementor** | [Consortium Member \xB7 Customer \xB7 TBD \u2014 required for Customer Workflow and Consumer Application tiers. When Consortium Member, link to org profile] |
|
|
6433
|
+
| **Customer** | [Link to customer org profile if this requirement originated from or applies to a specific customer. Optional for Platform/Industry tiers, expected for Customer Workflow/Consumer Application tiers] |
|
|
6434
|
+
| **Priority** | [Critical / High / Medium / Low] |
|
|
6435
|
+
| **Owner** | [Name or role responsible for this requirement] |
|
|
6436
|
+
| **Created** | YYYY-MM-DD |
|
|
6437
|
+
| **Last Updated** | YYYY-MM-DD |
|
|
6438
|
+
|
|
6439
|
+
## Business Need
|
|
6440
|
+
|
|
6441
|
+
A clear statement of the business problem or opportunity this requirement addresses. Focus on the "why" \u2014 what pain point exists, what opportunity we're capturing, or what strategic goal this supports.
|
|
6442
|
+
|
|
6443
|
+
## Stakeholders
|
|
6444
|
+
|
|
6445
|
+
| Stakeholder | Role | Interest |
|
|
6446
|
+
|---|---|---|
|
|
6447
|
+
| [Name/Group] | [Their role] | [What they care about regarding this requirement] |
|
|
6448
|
+
|
|
6449
|
+
## Success Metrics
|
|
6450
|
+
|
|
6451
|
+
Define how we'll know this requirement has been successfully met. Metrics should be specific and measurable.
|
|
6452
|
+
|
|
6453
|
+
| Metric | Target | Measurement Method |
|
|
6454
|
+
|---|---|---|
|
|
6455
|
+
| [e.g., Onboarding completion rate] | [e.g., > 80% within 7 days] | [e.g., Analytics funnel tracking] |
|
|
6456
|
+
|
|
6457
|
+
## Scope
|
|
6458
|
+
|
|
6459
|
+
### In Scope
|
|
6460
|
+
|
|
6461
|
+
What is explicitly included in this business requirement.
|
|
6462
|
+
|
|
6463
|
+
### Out of Scope
|
|
6464
|
+
|
|
6465
|
+
What is explicitly excluded \u2014 important for preventing scope creep and setting expectations.
|
|
6466
|
+
|
|
6467
|
+
## Assumptions
|
|
6468
|
+
|
|
6469
|
+
List assumptions that underpin this requirement. Flag any that carry risk if they turn out to be wrong.
|
|
6470
|
+
|
|
6471
|
+
- [Assumption 1]
|
|
6472
|
+
- [Assumption 2]
|
|
6473
|
+
|
|
6474
|
+
## Constraints
|
|
6475
|
+
|
|
6476
|
+
Business-level constraints that bound this requirement (budget, timeline, regulatory, organizational).
|
|
6477
|
+
|
|
6478
|
+
- [Constraint 1]
|
|
6479
|
+
- [Constraint 2]
|
|
6480
|
+
|
|
6481
|
+
## Dependencies
|
|
6482
|
+
|
|
6483
|
+
Other business requirements, external factors, or organizational decisions this requirement depends on.
|
|
6484
|
+
|
|
6485
|
+
- [Dependency 1]
|
|
6486
|
+
- [Dependency 2]
|
|
6487
|
+
|
|
6488
|
+
## Traceability
|
|
6489
|
+
|
|
6490
|
+
- **Decomposes into:** [FR-NNN](../functional/FR-NNN-slug.md), [FR-NNN](../functional/FR-NNN-slug.md)
|
|
6491
|
+
- **Constrained by:** [NFR-NNN](../non-functional/NFR-NNN-slug.md)
|
|
6492
|
+
- **Related:** [SEC-NNN](../security/SEC-NNN-slug.md)
|
|
6493
|
+
- **Depends on (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [platform/industry requirement this depends on]
|
|
6494
|
+
- **Enables (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [customer-workflow/consumer-app requirement this enables]
|
|
6495
|
+
|
|
6496
|
+
## Open Items
|
|
6497
|
+
|
|
6498
|
+
### Identified Gaps
|
|
6499
|
+
|
|
6500
|
+
[Document any missing functionality, unhandled edge cases, or incomplete aspects. Number each item and assign a priority (P0/P1/P2/P3). Call out interdependencies with other open items. If none, write "None identified."]
|
|
6501
|
+
|
|
6502
|
+
1. **[Gap title]** \`[P0-P3]\`
|
|
6503
|
+
[Description of what's missing and why it matters.]
|
|
6504
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
6505
|
+
|
|
6506
|
+
### Follow-up Questions
|
|
6507
|
+
|
|
6508
|
+
[Document anything ambiguous or where the motivation/reasoning cannot be confidently inferred. Number each item and assign a priority. If none, write "None identified."]
|
|
6509
|
+
|
|
6510
|
+
1. **[Question title]** \`[P0-P3]\`
|
|
6511
|
+
[The question, with context on why the answer matters.]
|
|
6512
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
6513
|
+
|
|
6514
|
+
### Contradictions & Inconsistencies
|
|
6515
|
+
|
|
6516
|
+
[Document any conflicts with other requirements, code behavior, or documentation. Number each item and assign a priority. If none, write "None identified."]
|
|
6517
|
+
|
|
6518
|
+
1. **[Contradiction title]** \`[P0-P3]\`
|
|
6519
|
+
[Description of the conflict and what needs to be resolved.]
|
|
6520
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
6521
|
+
|
|
6522
|
+
## Revision History
|
|
6523
|
+
|
|
6524
|
+
| Date | Author | Change |
|
|
6525
|
+
|---|---|---|
|
|
6526
|
+
| YYYY-MM-DD | [Name] | Initial draft |
|
|
6527
|
+
`;
|
|
6528
|
+
var TEMPLATE_FR = `---
|
|
6529
|
+
title: "FR-NNN: [Functional Requirement Title]"
|
|
6530
|
+
---
|
|
6531
|
+
|
|
6532
|
+
# FR-NNN: [Functional Requirement Title]
|
|
6533
|
+
|
|
6534
|
+
## Metadata
|
|
6535
|
+
|
|
6536
|
+
| Field | Value |
|
|
6537
|
+
|---|---|
|
|
6538
|
+
| **ID** | FR-NNN |
|
|
6539
|
+
| **Status** | Draft |
|
|
6540
|
+
| **Tier** | [Platform \xB7 Industry \xB7 Customer Workflow \xB7 Consumer Application] |
|
|
6541
|
+
| **Implementor** | [Consortium Member \xB7 Customer \xB7 TBD \u2014 required for Customer Workflow and Consumer Application tiers. When Consortium Member, link to org profile] |
|
|
6542
|
+
| **Customer** | [Link to customer org profile if this requirement originated from or applies to a specific customer. Optional for Platform/Industry tiers, expected for Customer Workflow/Consumer Application tiers] |
|
|
6543
|
+
| **Priority** | [Must Have / Should Have / Could Have / Won't Have] |
|
|
6544
|
+
| **Owner** | [Name or role] |
|
|
6545
|
+
| **Created** | YYYY-MM-DD |
|
|
6546
|
+
| **Last Updated** | YYYY-MM-DD |
|
|
6547
|
+
|
|
6548
|
+
## User Story
|
|
6549
|
+
|
|
6550
|
+
**As a** [actor/role],
|
|
6551
|
+
**I want to** [action/capability],
|
|
6552
|
+
**So that** [business value/outcome].
|
|
6553
|
+
|
|
6554
|
+
## Description
|
|
6555
|
+
|
|
6556
|
+
A narrative description of this feature or behavior. Include enough context that someone unfamiliar with the project can understand what the system does and why it matters.
|
|
6557
|
+
|
|
6558
|
+
## Actors
|
|
6559
|
+
|
|
6560
|
+
| Actor | Description |
|
|
6561
|
+
|---|---|
|
|
6562
|
+
| [e.g., Registered User] | [Who they are and what access level they have] |
|
|
6563
|
+
|
|
6564
|
+
## Preconditions
|
|
6565
|
+
|
|
6566
|
+
Conditions that must be true before this functionality can be used.
|
|
6567
|
+
|
|
6568
|
+
- [Precondition 1]
|
|
6569
|
+
- [Precondition 2]
|
|
6570
|
+
|
|
6571
|
+
## Main Flow
|
|
6572
|
+
|
|
6573
|
+
The primary happy-path sequence of interactions.
|
|
6574
|
+
|
|
6575
|
+
1. [Step 1]
|
|
6576
|
+
2. [Step 2]
|
|
6577
|
+
3. [Step 3]
|
|
6578
|
+
|
|
6579
|
+
## Alternative Flows
|
|
6580
|
+
|
|
6581
|
+
### AF-1: [Alternative Flow Name]
|
|
6582
|
+
|
|
6583
|
+
**Trigger:** [What causes this alternative path]
|
|
6584
|
+
|
|
6585
|
+
1. [Step 1]
|
|
6586
|
+
2. [Step 2]
|
|
6587
|
+
|
|
6588
|
+
### AF-2: [Alternative Flow Name]
|
|
6589
|
+
|
|
6590
|
+
**Trigger:** [What causes this alternative path]
|
|
6591
|
+
|
|
6592
|
+
1. [Step 1]
|
|
6593
|
+
2. [Step 2]
|
|
6594
|
+
|
|
6595
|
+
## Exception Flows
|
|
6596
|
+
|
|
6597
|
+
### EF-1: [Exception Flow Name]
|
|
6598
|
+
|
|
6599
|
+
**Trigger:** [What error condition causes this]
|
|
6600
|
+
|
|
6601
|
+
1. [Step 1 \u2014 how the system responds]
|
|
6602
|
+
2. [Step 2]
|
|
6603
|
+
|
|
6604
|
+
## Acceptance Criteria
|
|
6605
|
+
|
|
6606
|
+
Specific, testable conditions that must be met for this requirement to be considered complete.
|
|
6607
|
+
|
|
6608
|
+
- [ ] [Criterion 1 \u2014 stated as a concrete, verifiable condition]
|
|
6609
|
+
- [ ] [Criterion 2]
|
|
6610
|
+
- [ ] [Criterion 3]
|
|
6611
|
+
|
|
6612
|
+
## Business Rules
|
|
6613
|
+
|
|
6614
|
+
Rules that govern the behavior described in this requirement.
|
|
6615
|
+
|
|
6616
|
+
| Rule ID | Description |
|
|
6617
|
+
|---|---|
|
|
6618
|
+
| BIZ-01 | [e.g., Email addresses must be unique across the system] |
|
|
6619
|
+
| BIZ-02 | [e.g., Passwords must be at least 12 characters] |
|
|
6620
|
+
|
|
6621
|
+
## UI/UX Considerations
|
|
6622
|
+
|
|
6623
|
+
Notes on how this feature should present to the user. Reference UX requirements where applicable.
|
|
6624
|
+
|
|
6625
|
+
## Data Requirements
|
|
6626
|
+
|
|
6627
|
+
What data is created, read, updated, or deleted by this feature. Reference DR documents where applicable.
|
|
6628
|
+
|
|
6629
|
+
## Traceability
|
|
6630
|
+
|
|
6631
|
+
- **Implements:** [BR-NNN](../business/BR-NNN-slug.md)
|
|
6632
|
+
- **Constrained by:** [NFR-NNN](../non-functional/NFR-NNN-slug.md)
|
|
6633
|
+
- **Related:** [INT-NNN](../integration/INT-NNN-slug.md)
|
|
6634
|
+
- **Depends on (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [platform/industry requirement this depends on]
|
|
6635
|
+
- **Enables (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [customer-workflow/consumer-app requirement this enables]
|
|
6636
|
+
|
|
6637
|
+
## Open Items
|
|
6638
|
+
|
|
6639
|
+
### Identified Gaps
|
|
6640
|
+
|
|
6641
|
+
[Document any missing functionality, unhandled edge cases, or incomplete aspects. Number each item and assign a priority (P0/P1/P2/P3). Call out interdependencies with other open items. If none, write "None identified."]
|
|
6642
|
+
|
|
6643
|
+
1. **[Gap title]** \`[P0-P3]\`
|
|
6644
|
+
[Description of what's missing and why it matters.]
|
|
6645
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
6646
|
+
|
|
6647
|
+
### Follow-up Questions
|
|
6648
|
+
|
|
6649
|
+
[Document anything ambiguous or where the motivation/reasoning cannot be confidently inferred. Number each item and assign a priority. If none, write "None identified."]
|
|
6650
|
+
|
|
6651
|
+
1. **[Question title]** \`[P0-P3]\`
|
|
6652
|
+
[The question, with context on why the answer matters.]
|
|
6653
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
6654
|
+
|
|
6655
|
+
### Contradictions & Inconsistencies
|
|
6656
|
+
|
|
6657
|
+
[Document any conflicts with other requirements, code behavior, or documentation. Number each item and assign a priority. If none, write "None identified."]
|
|
6658
|
+
|
|
6659
|
+
1. **[Contradiction title]** \`[P0-P3]\`
|
|
6660
|
+
[Description of the conflict and what needs to be resolved.]
|
|
6661
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
6662
|
+
|
|
6663
|
+
## Revision History
|
|
6664
|
+
|
|
6665
|
+
| Date | Author | Change |
|
|
6666
|
+
|---|---|---|
|
|
6667
|
+
| YYYY-MM-DD | [Name] | Initial draft |
|
|
6668
|
+
`;
|
|
6669
|
+
var TEMPLATE_NFR = `---
|
|
6670
|
+
title: "NFR-NNN: [Non-Functional Requirement Title]"
|
|
6671
|
+
---
|
|
6672
|
+
|
|
6673
|
+
# NFR-NNN: [Non-Functional Requirement Title]
|
|
6674
|
+
|
|
6675
|
+
## Metadata
|
|
6676
|
+
|
|
6677
|
+
| Field | Value |
|
|
6678
|
+
|---|---|
|
|
6679
|
+
| **ID** | NFR-NNN |
|
|
6680
|
+
| **Status** | Draft |
|
|
6681
|
+
| **Tier** | [Platform \xB7 Industry \xB7 Customer Workflow \xB7 Consumer Application] |
|
|
6682
|
+
| **Implementor** | [Consortium Member \xB7 Customer \xB7 TBD \u2014 required for Customer Workflow and Consumer Application tiers. When Consortium Member, link to org profile] |
|
|
6683
|
+
| **Customer** | [Link to customer org profile if this requirement originated from or applies to a specific customer. Optional for Platform/Industry tiers, expected for Customer Workflow/Consumer Application tiers] |
|
|
6684
|
+
| **Quality Attribute** | [Performance / Reliability / Scalability / Maintainability / Portability / Availability] |
|
|
6685
|
+
| **Priority** | [Critical / High / Medium / Low] |
|
|
6686
|
+
| **Owner** | [Name or role] |
|
|
6687
|
+
| **Created** | YYYY-MM-DD |
|
|
6688
|
+
| **Last Updated** | YYYY-MM-DD |
|
|
6689
|
+
|
|
6690
|
+
## Description
|
|
6691
|
+
|
|
6692
|
+
What quality attribute this requirement addresses and why it matters for the system.
|
|
6693
|
+
|
|
6694
|
+
## Measurable Targets
|
|
6695
|
+
|
|
6696
|
+
Non-functional requirements must have numeric, measurable targets \u2014 vague statements like "the system should be fast" are not acceptable.
|
|
6697
|
+
|
|
6698
|
+
| Metric | Target | Measurement Method | Measurement Frequency |
|
|
6699
|
+
|---|---|---|---|
|
|
6700
|
+
| [e.g., API response time (p99)] | [e.g., < 200ms] | [e.g., Datadog APM percentile tracking] | [e.g., Continuous] |
|
|
6701
|
+
| [e.g., System availability] | [e.g., 99.9% monthly] | [e.g., Uptime monitoring (Pingdom/UptimeRobot)] | [e.g., Monthly] |
|
|
6702
|
+
|
|
6703
|
+
## Current Baseline
|
|
6704
|
+
|
|
6705
|
+
If this is being applied to an existing system, document the current measured values so improvement can be tracked.
|
|
6706
|
+
|
|
6707
|
+
| Metric | Current Value | Date Measured |
|
|
6708
|
+
|---|---|---|
|
|
6709
|
+
| [Metric] | [Current value or "Not yet measured"] | [Date] |
|
|
6710
|
+
|
|
6711
|
+
## Rationale
|
|
6712
|
+
|
|
6713
|
+
Why this target was chosen. What business need or user expectation drives this number? What are the consequences of not meeting it?
|
|
6714
|
+
|
|
6715
|
+
## Applicable Scope
|
|
6716
|
+
|
|
6717
|
+
Which parts of the system does this requirement apply to? Be specific \u2014 "all API endpoints" or "the checkout flow" rather than "the system."
|
|
6718
|
+
|
|
6719
|
+
## Approach
|
|
6720
|
+
|
|
6721
|
+
High-level approach for meeting this target. Reference ADRs and TRs for implementation details.
|
|
6722
|
+
|
|
6723
|
+
## Monitoring & Alerting
|
|
6724
|
+
|
|
6725
|
+
How compliance with this requirement will be monitored in production. Reference OPS requirements where applicable.
|
|
6726
|
+
|
|
6727
|
+
| Alert Condition | Threshold | Action |
|
|
6728
|
+
|---|---|---|
|
|
6729
|
+
| [e.g., p99 latency exceeds target] | [e.g., > 200ms for 5 minutes] | [e.g., Page on-call engineer] |
|
|
6730
|
+
|
|
6731
|
+
## Traceability
|
|
6732
|
+
|
|
6733
|
+
- **Supports:** [BR-NNN](../business/BR-NNN-slug.md)
|
|
6734
|
+
- **Constrains:** [FR-NNN](../functional/FR-NNN-slug.md)
|
|
6735
|
+
- **Monitored by:** [OPS-NNN](../operational/OPS-NNN-slug.md)
|
|
6736
|
+
- **Depends on (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [platform/industry requirement this depends on]
|
|
6737
|
+
- **Enables (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [customer-workflow/consumer-app requirement this enables]
|
|
6738
|
+
|
|
6739
|
+
## Open Items
|
|
6740
|
+
|
|
6741
|
+
### Identified Gaps
|
|
6742
|
+
|
|
6743
|
+
[Document any missing functionality, unhandled edge cases, or incomplete aspects. Number each item and assign a priority (P0/P1/P2/P3). Call out interdependencies with other open items. If none, write "None identified."]
|
|
6744
|
+
|
|
6745
|
+
1. **[Gap title]** \`[P0-P3]\`
|
|
6746
|
+
[Description of what's missing and why it matters.]
|
|
6747
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
6748
|
+
|
|
6749
|
+
### Follow-up Questions
|
|
6750
|
+
|
|
6751
|
+
[Document anything ambiguous or where the motivation/reasoning cannot be confidently inferred. Number each item and assign a priority. If none, write "None identified."]
|
|
6752
|
+
|
|
6753
|
+
1. **[Question title]** \`[P0-P3]\`
|
|
6754
|
+
[The question, with context on why the answer matters.]
|
|
6755
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
6756
|
+
|
|
6757
|
+
### Contradictions & Inconsistencies
|
|
6758
|
+
|
|
6759
|
+
[Document any conflicts with other requirements, code behavior, or documentation. Number each item and assign a priority. If none, write "None identified."]
|
|
6760
|
+
|
|
6761
|
+
1. **[Contradiction title]** \`[P0-P3]\`
|
|
6762
|
+
[Description of the conflict and what needs to be resolved.]
|
|
6763
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
6764
|
+
|
|
6765
|
+
## Revision History
|
|
6766
|
+
|
|
6767
|
+
| Date | Author | Change |
|
|
6768
|
+
|---|---|---|
|
|
6769
|
+
| YYYY-MM-DD | [Name] | Initial draft |
|
|
6770
|
+
`;
|
|
6771
|
+
var TEMPLATE_TR = `---
|
|
6772
|
+
title: "TR-NNN: [Technical Requirement Title]"
|
|
6773
|
+
---
|
|
6774
|
+
|
|
6775
|
+
# TR-NNN: [Technical Requirement Title]
|
|
6776
|
+
|
|
6777
|
+
## Metadata
|
|
6778
|
+
|
|
6779
|
+
| Field | Value |
|
|
6780
|
+
|---|---|
|
|
6781
|
+
| **ID** | TR-NNN |
|
|
6782
|
+
| **Status** | Draft |
|
|
6783
|
+
| **Tier** | [Platform \xB7 Industry \xB7 Customer Workflow \xB7 Consumer Application] |
|
|
6784
|
+
| **Implementor** | [Consortium Member \xB7 Customer \xB7 TBD \u2014 required for Customer Workflow and Consumer Application tiers. When Consortium Member, link to org profile] |
|
|
6785
|
+
| **Customer** | [Link to customer org profile if this requirement originated from or applies to a specific customer. Optional for Platform/Industry tiers, expected for Customer Workflow/Consumer Application tiers] |
|
|
6786
|
+
| **Category** | [Language / Framework / Database / Infrastructure / Library / Tool] |
|
|
6787
|
+
| **Owner** | [Name or role] |
|
|
6788
|
+
| **Created** | YYYY-MM-DD |
|
|
6789
|
+
| **Last Updated** | YYYY-MM-DD |
|
|
6790
|
+
|
|
6791
|
+
## Technology Choice
|
|
6792
|
+
|
|
6793
|
+
When **Accepted**: Fill in the selected technology.
|
|
6794
|
+
|
|
6795
|
+
When **Proposed**: Write "Pending human review. See Recommendation below." and leave Version/License/Vendor as TBD.
|
|
6796
|
+
|
|
6797
|
+
| Field | Value |
|
|
6798
|
+
|---|---|
|
|
6799
|
+
| **Technology** | [e.g., PostgreSQL] |
|
|
6800
|
+
| **Version** | [e.g., 16+ (observed: 16-alpine at time of documentation). Version will naturally drift upward through routine maintenance.] |
|
|
6801
|
+
| **License** | [e.g., PostgreSQL License (permissive, OSI-approved)] |
|
|
6802
|
+
| **Vendor/Maintainer** | [e.g., PostgreSQL Global Development Group] |
|
|
6803
|
+
|
|
6804
|
+
## Alternatives Considered
|
|
6805
|
+
|
|
6806
|
+
List every viable technology option, including the recommended one. Each alternative gets the same level of analysis.
|
|
6807
|
+
|
|
6808
|
+
### Option 1: [Technology Name]
|
|
6809
|
+
|
|
6810
|
+
**Description:** [What this technology is and how it would be used]
|
|
6811
|
+
|
|
6812
|
+
**Pros:**
|
|
6813
|
+
- [Pro 1]
|
|
6814
|
+
- [Pro 2]
|
|
6815
|
+
|
|
6816
|
+
**Cons:**
|
|
6817
|
+
- [Con 1]
|
|
6818
|
+
- [Con 2]
|
|
6819
|
+
|
|
6820
|
+
**License:** [License type]
|
|
6821
|
+
**Maturity:** [Established / Growing / Emerging]
|
|
6822
|
+
|
|
6823
|
+
### Option 2: [Technology Name]
|
|
6824
|
+
|
|
6825
|
+
**Description:** [What this technology is and how it would be used]
|
|
6826
|
+
|
|
6827
|
+
**Pros:**
|
|
6828
|
+
- [Pro 1]
|
|
6829
|
+
|
|
6830
|
+
**Cons:**
|
|
6831
|
+
- [Con 1]
|
|
6832
|
+
|
|
6833
|
+
**License:** [License type]
|
|
6834
|
+
**Maturity:** [Established / Growing / Emerging]
|
|
6835
|
+
|
|
6836
|
+
## Recommendation
|
|
6837
|
+
|
|
6838
|
+
**Recommended option:** [Name of the recommended technology]
|
|
6839
|
+
|
|
6840
|
+
**Why this option:** [A well-reasoned explanation of why this technology best fits the context, constraints, and goals. Address the key trade-offs honestly \u2014 explain why the cons are acceptable and why other options were not preferred.]
|
|
6841
|
+
|
|
6842
|
+
**Key trade-offs accepted:** [What you're giving up by choosing this option over others]
|
|
6843
|
+
|
|
6844
|
+
When the status is \`Proposed\`, this section frames the decision for the human reviewer. When \`Accepted\`, this section documents the reasoning behind the choice.
|
|
6845
|
+
|
|
6846
|
+
## Rationale
|
|
6847
|
+
|
|
6848
|
+
When **Accepted**: Summarize why this technology was selected. Reference the ADR that records the decision process if one exists.
|
|
6849
|
+
|
|
6850
|
+
When **Proposed**: Write "See Recommendation above. Awaiting human decision."
|
|
6851
|
+
|
|
6852
|
+
## Usage Context
|
|
6853
|
+
|
|
6854
|
+
How and where this technology is used in the system. Be specific about which components or layers depend on it.
|
|
6855
|
+
|
|
6856
|
+
## Version Constraints
|
|
6857
|
+
|
|
6858
|
+
Any version pinning, upgrade policies, or compatibility requirements. Assume versions will drift upward over time through routine maintenance unless there is a specific reason to pin.
|
|
6859
|
+
|
|
6860
|
+
- **Minimum version:** [version \u2014 the floor below which compatibility is not guaranteed]
|
|
6861
|
+
- **Observed version:** [version at time of documentation]
|
|
6862
|
+
- **Maximum version:** [version or "latest stable" \u2014 only specify if there's a known ceiling]
|
|
6863
|
+
- **Upgrade policy:** [e.g., "Track latest minor releases within 30 days; major version upgrades require ADR"]
|
|
6864
|
+
- **Version-sensitive notes:** [Any specific features or APIs used that depend on this version floor \u2014 helps future developers understand what might break if they don't meet the minimum]
|
|
6865
|
+
|
|
6866
|
+
## Configuration Standards
|
|
6867
|
+
|
|
6868
|
+
Key configuration decisions, defaults, or standards that apply to this technology across the project.
|
|
6869
|
+
|
|
6870
|
+
## Dependencies & Compatibility
|
|
6871
|
+
|
|
6872
|
+
Other technologies this choice interacts with, and any known compatibility constraints.
|
|
6873
|
+
|
|
6874
|
+
| Dependency | Relationship | Constraint |
|
|
6875
|
+
|---|---|---|
|
|
6876
|
+
| [e.g., Node.js runtime] | [Required by] | [e.g., v18 LTS or later] |
|
|
6877
|
+
|
|
6878
|
+
## Risks & Mitigations
|
|
6879
|
+
|
|
6880
|
+
| Risk | Likelihood | Impact | Mitigation |
|
|
6881
|
+
|---|---|---|---|
|
|
6882
|
+
| [e.g., Vendor discontinues support] | [Low/Medium/High] | [Low/Medium/High] | [e.g., Open-source, community-maintained] |
|
|
6883
|
+
|
|
6884
|
+
## Traceability
|
|
6885
|
+
|
|
6886
|
+
- **Justified by:** [ADR-NNN](../architectural-decisions/ADR-NNN-slug.md)
|
|
6887
|
+
- **Supports:** [FR-NNN](../functional/FR-NNN-slug.md)
|
|
6888
|
+
- **Constrained by:** [NFR-NNN](../non-functional/NFR-NNN-slug.md)
|
|
6889
|
+
- **Depends on (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [platform/industry requirement this depends on]
|
|
6890
|
+
- **Enables (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [customer-workflow/consumer-app requirement this enables]
|
|
6891
|
+
|
|
6892
|
+
## Open Items
|
|
6893
|
+
|
|
6894
|
+
### Identified Gaps
|
|
6895
|
+
|
|
6896
|
+
[Document any missing functionality, unhandled edge cases, or incomplete aspects. Number each item and assign a priority (P0/P1/P2/P3). Call out interdependencies with other open items. If none, write "None identified."]
|
|
6897
|
+
|
|
6898
|
+
1. **[Gap title]** \`[P0-P3]\`
|
|
6899
|
+
[Description of what's missing and why it matters.]
|
|
6900
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
6901
|
+
|
|
6902
|
+
### Follow-up Questions
|
|
6903
|
+
|
|
6904
|
+
[Document anything ambiguous or where the motivation/reasoning cannot be confidently inferred. Number each item and assign a priority. If none, write "None identified."]
|
|
6905
|
+
|
|
6906
|
+
1. **[Question title]** \`[P0-P3]\`
|
|
6907
|
+
[The question, with context on why the answer matters.]
|
|
6908
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
6909
|
+
|
|
6910
|
+
### Contradictions & Inconsistencies
|
|
6911
|
+
|
|
6912
|
+
[Document any conflicts with other requirements, code behavior, or documentation. Number each item and assign a priority. If none, write "None identified."]
|
|
6913
|
+
|
|
6914
|
+
1. **[Contradiction title]** \`[P0-P3]\`
|
|
6915
|
+
[Description of the conflict and what needs to be resolved.]
|
|
6916
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
6917
|
+
|
|
6918
|
+
## Revision History
|
|
6919
|
+
|
|
6920
|
+
| Date | Author | Change |
|
|
6921
|
+
|---|---|---|
|
|
6922
|
+
| YYYY-MM-DD | [Name] | Initial draft |
|
|
6923
|
+
`;
|
|
6924
|
+
var TEMPLATE_ADR = `---
|
|
6925
|
+
title: "ADR-NNN: [Decision Title]"
|
|
6926
|
+
---
|
|
6927
|
+
|
|
6928
|
+
# ADR-NNN: [Decision Title]
|
|
6929
|
+
|
|
6930
|
+
## Metadata
|
|
6931
|
+
|
|
6932
|
+
| Field | Value |
|
|
6933
|
+
|---|---|
|
|
6934
|
+
| **ID** | ADR-NNN |
|
|
6935
|
+
| **Status** | Draft |
|
|
6936
|
+
| **Tier** | [Platform \xB7 Industry \xB7 Customer Workflow \xB7 Consumer Application] |
|
|
6937
|
+
| **Implementor** | [Consortium Member \xB7 Customer \xB7 TBD \u2014 required for Customer Workflow and Consumer Application tiers. When Consortium Member, link to org profile] |
|
|
6938
|
+
| **Customer** | [Link to customer org profile if this requirement originated from or applies to a specific customer. Optional for Platform/Industry tiers, expected for Customer Workflow/Consumer Application tiers] |
|
|
6939
|
+
| **Decision Date** | YYYY-MM-DD |
|
|
6940
|
+
| **Decision Makers** | [Names or roles involved in the decision] |
|
|
6941
|
+
| **Created** | YYYY-MM-DD |
|
|
6942
|
+
| **Last Updated** | YYYY-MM-DD |
|
|
6943
|
+
|
|
6944
|
+
## Context
|
|
6945
|
+
|
|
6946
|
+
What is the issue that we're seeing that motivates this decision or change? What forces are at play \u2014 technical constraints, business pressures, team capabilities, timeline?
|
|
6947
|
+
|
|
6948
|
+
## Decision
|
|
6949
|
+
|
|
6950
|
+
When **Accepted**: State the architectural decision clearly and concisely. Start with "We will..." or "We have decided to..."
|
|
6951
|
+
|
|
6952
|
+
When **Proposed**: Write "Pending human review. See Recommendation below." Do not make the decision \u2014 present the analysis so a human can decide.
|
|
6953
|
+
|
|
6954
|
+
## Alternatives Considered
|
|
6955
|
+
|
|
6956
|
+
List every viable option, including the recommended one. Each alternative gets the same level of analysis \u2014 do not shortchange options you don't prefer.
|
|
6957
|
+
|
|
6958
|
+
### Alternative 1: [Name]
|
|
6959
|
+
|
|
6960
|
+
**Description:** [What this alternative entails \u2014 enough detail to evaluate it]
|
|
6961
|
+
|
|
6962
|
+
**Pros:**
|
|
6963
|
+
- [Pro 1]
|
|
6964
|
+
- [Pro 2]
|
|
6965
|
+
|
|
6966
|
+
**Cons:**
|
|
6967
|
+
- [Con 1]
|
|
6968
|
+
- [Con 2]
|
|
6969
|
+
|
|
6970
|
+
### Alternative 2: [Name]
|
|
6971
|
+
|
|
6972
|
+
**Description:** [What this alternative entails]
|
|
6973
|
+
|
|
6974
|
+
**Pros:**
|
|
6975
|
+
- [Pro 1]
|
|
6976
|
+
|
|
6977
|
+
**Cons:**
|
|
6978
|
+
- [Con 1]
|
|
6979
|
+
|
|
6980
|
+
## Recommendation
|
|
6981
|
+
|
|
6982
|
+
**Recommended option:** [Name of the recommended alternative]
|
|
6983
|
+
|
|
6984
|
+
**Why this option:** [A well-reasoned explanation of why this alternative best fits the context, constraints, and goals. Address the key trade-offs honestly \u2014 explain why the cons of the recommended option are acceptable and why the pros of rejected alternatives don't outweigh their cons in this context.]
|
|
6985
|
+
|
|
6986
|
+
**Key trade-offs accepted:** [What you're giving up by choosing this option over others]
|
|
6987
|
+
|
|
6988
|
+
When the status is \`Proposed\`, this section frames the decision for the human reviewer. When \`Accepted\`, this section documents the reasoning behind the choice.
|
|
6989
|
+
|
|
6990
|
+
## Consequences
|
|
6991
|
+
|
|
6992
|
+
### Positive
|
|
6993
|
+
|
|
6994
|
+
- [Positive consequence 1]
|
|
6995
|
+
- [Positive consequence 2]
|
|
6996
|
+
|
|
6997
|
+
### Negative
|
|
6998
|
+
|
|
6999
|
+
- [Negative consequence 1 \u2014 every decision has trade-offs; document them honestly]
|
|
7000
|
+
- [Negative consequence 2]
|
|
7001
|
+
|
|
7002
|
+
### Neutral
|
|
7003
|
+
|
|
7004
|
+
- [Neutral observation about what changes as a result of this decision]
|
|
7005
|
+
|
|
7006
|
+
## Compliance & Constraints
|
|
7007
|
+
|
|
7008
|
+
Any regulatory, security, or organizational constraints that influenced this decision.
|
|
7009
|
+
|
|
7010
|
+
## Implementation Notes
|
|
7011
|
+
|
|
7012
|
+
High-level guidance for implementing this decision. Detailed implementation goes in TR and FR documents.
|
|
7013
|
+
|
|
7014
|
+
## Traceability
|
|
7015
|
+
|
|
7016
|
+
- **Supports:** [BR-NNN](../business/BR-NNN-slug.md)
|
|
7017
|
+
- **Implemented by:** [TR-NNN](../technical/TR-NNN-slug.md)
|
|
7018
|
+
- **Related:** [ADR-NNN](ADR-NNN-slug.md)
|
|
7019
|
+
- **Depends on (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [platform/industry requirement this depends on]
|
|
7020
|
+
- **Enables (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [customer-workflow/consumer-app requirement this enables]
|
|
7021
|
+
|
|
7022
|
+
## Open Items
|
|
7023
|
+
|
|
7024
|
+
### Identified Gaps
|
|
7025
|
+
|
|
7026
|
+
[Document any missing functionality, unhandled edge cases, or incomplete aspects. Number each item and assign a priority (P0/P1/P2/P3). Call out interdependencies with other open items. If none, write "None identified."]
|
|
7027
|
+
|
|
7028
|
+
1. **[Gap title]** \`[P0-P3]\`
|
|
7029
|
+
[Description of what's missing and why it matters.]
|
|
7030
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7031
|
+
|
|
7032
|
+
### Follow-up Questions
|
|
7033
|
+
|
|
7034
|
+
[Document anything ambiguous or where the motivation/reasoning cannot be confidently inferred. Number each item and assign a priority. If none, write "None identified."]
|
|
7035
|
+
|
|
7036
|
+
1. **[Question title]** \`[P0-P3]\`
|
|
7037
|
+
[The question, with context on why the answer matters.]
|
|
7038
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7039
|
+
|
|
7040
|
+
### Contradictions & Inconsistencies
|
|
7041
|
+
|
|
7042
|
+
[Document any conflicts with other requirements, code behavior, or documentation. Number each item and assign a priority. If none, write "None identified."]
|
|
7043
|
+
|
|
7044
|
+
1. **[Contradiction title]** \`[P0-P3]\`
|
|
7045
|
+
[Description of the conflict and what needs to be resolved.]
|
|
7046
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7047
|
+
|
|
7048
|
+
## Revision History
|
|
7049
|
+
|
|
7050
|
+
| Date | Author | Change |
|
|
7051
|
+
|---|---|---|
|
|
7052
|
+
| YYYY-MM-DD | [Name] | Initial draft |
|
|
7053
|
+
`;
|
|
7054
|
+
var TEMPLATE_SEC = `---
|
|
7055
|
+
title: "SEC-NNN: [Security Requirement Title]"
|
|
7056
|
+
---
|
|
7057
|
+
|
|
7058
|
+
# SEC-NNN: [Security Requirement Title]
|
|
7059
|
+
|
|
7060
|
+
## Metadata
|
|
7061
|
+
|
|
7062
|
+
| Field | Value |
|
|
7063
|
+
|---|---|
|
|
7064
|
+
| **ID** | SEC-NNN |
|
|
7065
|
+
| **Status** | Draft |
|
|
7066
|
+
| **Tier** | [Platform \xB7 Industry \xB7 Customer Workflow \xB7 Consumer Application] |
|
|
7067
|
+
| **Implementor** | [Consortium Member \xB7 Customer \xB7 TBD \u2014 required for Customer Workflow and Consumer Application tiers. When Consortium Member, link to org profile] |
|
|
7068
|
+
| **Customer** | [Link to customer org profile if this requirement originated from or applies to a specific customer. Optional for Platform/Industry tiers, expected for Customer Workflow/Consumer Application tiers] |
|
|
7069
|
+
| **Security Domain** | [Authentication / Authorization / Data Protection / Audit / Compliance / Network / Input Validation] |
|
|
7070
|
+
| **Priority** | [Critical / High / Medium / Low] |
|
|
7071
|
+
| **Owner** | [Name or role] |
|
|
7072
|
+
| **Created** | YYYY-MM-DD |
|
|
7073
|
+
| **Last Updated** | YYYY-MM-DD |
|
|
7074
|
+
|
|
7075
|
+
## Description
|
|
7076
|
+
|
|
7077
|
+
What security concern this requirement addresses and why it matters.
|
|
7078
|
+
|
|
7079
|
+
## Threat Model Reference
|
|
7080
|
+
|
|
7081
|
+
What threats does this requirement mitigate? Reference any formal threat modeling artifacts if they exist.
|
|
7082
|
+
|
|
7083
|
+
| Threat | STRIDE Category | Severity | This Requirement Mitigates |
|
|
7084
|
+
|---|---|---|---|
|
|
7085
|
+
| [e.g., Unauthorized access to tenant data] | [e.g., Elevation of Privilege] | [Critical/High/Medium/Low] | [How] |
|
|
7086
|
+
|
|
7087
|
+
## Requirements
|
|
7088
|
+
|
|
7089
|
+
### Controls
|
|
7090
|
+
|
|
7091
|
+
Specific security controls that must be implemented.
|
|
7092
|
+
|
|
7093
|
+
| Control ID | Description | OWASP ASVS Ref | NIST 800-53 Ref |
|
|
7094
|
+
|---|---|---|---|
|
|
7095
|
+
| [e.g., SEC-001-C1] | [e.g., All passwords hashed with bcrypt, cost factor \u2265 12] | [e.g., V2.4.1] | [e.g., IA-5(1)] |
|
|
7096
|
+
|
|
7097
|
+
### Policies
|
|
7098
|
+
|
|
7099
|
+
Organizational or procedural security policies this requirement enforces.
|
|
7100
|
+
|
|
7101
|
+
- [Policy 1]
|
|
7102
|
+
- [Policy 2]
|
|
7103
|
+
|
|
7104
|
+
## Applicable Regulations
|
|
7105
|
+
|
|
7106
|
+
| Regulation | Requirement | How We Comply |
|
|
7107
|
+
|---|---|---|
|
|
7108
|
+
| [e.g., SOC 2 Type II] | [e.g., Access controls and audit logging] | [e.g., RBAC + immutable audit log] |
|
|
7109
|
+
| [e.g., GDPR] | [e.g., Data encryption at rest] | [e.g., AES-256 via AWS KMS] |
|
|
7110
|
+
|
|
7111
|
+
## Validation Approach
|
|
7112
|
+
|
|
7113
|
+
How compliance with this security requirement will be verified.
|
|
7114
|
+
|
|
7115
|
+
| Method | Frequency | Responsible Party |
|
|
7116
|
+
|---|---|---|
|
|
7117
|
+
| [e.g., Automated security scan] | [e.g., Every CI build] | [e.g., DevOps] |
|
|
7118
|
+
| [e.g., Penetration test] | [e.g., Annually] | [e.g., External vendor] |
|
|
7119
|
+
|
|
7120
|
+
## Acceptance Criteria
|
|
7121
|
+
|
|
7122
|
+
- [ ] [Specific, verifiable security condition]
|
|
7123
|
+
- [ ] [e.g., No passwords stored in plaintext anywhere in the system]
|
|
7124
|
+
- [ ] [e.g., All API endpoints require authentication except explicitly whitelisted public routes]
|
|
7125
|
+
|
|
7126
|
+
## Traceability
|
|
7127
|
+
|
|
7128
|
+
- **Protects:** [FR-NNN](../functional/FR-NNN-slug.md)
|
|
7129
|
+
- **Constrained by:** [NFR-NNN](../non-functional/NFR-NNN-slug.md)
|
|
7130
|
+
- **Implements:** [BR-NNN](../business/BR-NNN-slug.md)
|
|
7131
|
+
- **Related data:** [DR-NNN](../data/DR-NNN-slug.md)
|
|
7132
|
+
- **Depends on (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [platform/industry requirement this depends on]
|
|
7133
|
+
- **Enables (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [customer-workflow/consumer-app requirement this enables]
|
|
7134
|
+
|
|
7135
|
+
## Open Items
|
|
7136
|
+
|
|
7137
|
+
### Identified Gaps
|
|
7138
|
+
|
|
7139
|
+
[Document any missing functionality, unhandled edge cases, or incomplete aspects. Number each item and assign a priority (P0/P1/P2/P3). Call out interdependencies with other open items. If none, write "None identified."]
|
|
7140
|
+
|
|
7141
|
+
1. **[Gap title]** \`[P0-P3]\`
|
|
7142
|
+
[Description of what's missing and why it matters.]
|
|
7143
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7144
|
+
|
|
7145
|
+
### Follow-up Questions
|
|
7146
|
+
|
|
7147
|
+
[Document anything ambiguous or where the motivation/reasoning cannot be confidently inferred. Number each item and assign a priority. If none, write "None identified."]
|
|
7148
|
+
|
|
7149
|
+
1. **[Question title]** \`[P0-P3]\`
|
|
7150
|
+
[The question, with context on why the answer matters.]
|
|
7151
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7152
|
+
|
|
7153
|
+
### Contradictions & Inconsistencies
|
|
7154
|
+
|
|
7155
|
+
[Document any conflicts with other requirements, code behavior, or documentation. Number each item and assign a priority. If none, write "None identified."]
|
|
7156
|
+
|
|
7157
|
+
1. **[Contradiction title]** \`[P0-P3]\`
|
|
7158
|
+
[Description of the conflict and what needs to be resolved.]
|
|
7159
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7160
|
+
|
|
7161
|
+
## Revision History
|
|
7162
|
+
|
|
7163
|
+
| Date | Author | Change |
|
|
7164
|
+
|---|---|---|
|
|
7165
|
+
| YYYY-MM-DD | [Name] | Initial draft |
|
|
7166
|
+
`;
|
|
7167
|
+
var TEMPLATE_DR = `---
|
|
7168
|
+
title: "DR-NNN: [Data Requirement Title]"
|
|
7169
|
+
---
|
|
7170
|
+
|
|
7171
|
+
# DR-NNN: [Data Requirement Title]
|
|
7172
|
+
|
|
7173
|
+
## Metadata
|
|
7174
|
+
|
|
7175
|
+
| Field | Value |
|
|
7176
|
+
|---|---|
|
|
7177
|
+
| **ID** | DR-NNN |
|
|
7178
|
+
| **Status** | Draft |
|
|
7179
|
+
| **Tier** | [Platform \xB7 Industry \xB7 Customer Workflow \xB7 Consumer Application] |
|
|
7180
|
+
| **Implementor** | [Consortium Member \xB7 Customer \xB7 TBD \u2014 required for Customer Workflow and Consumer Application tiers. When Consortium Member, link to org profile] |
|
|
7181
|
+
| **Customer** | [Link to customer org profile if this requirement originated from or applies to a specific customer. Optional for Platform/Industry tiers, expected for Customer Workflow/Consumer Application tiers] |
|
|
7182
|
+
| **Data Domain** | [e.g., User Data / Transaction Data / Configuration / Audit Logs / Media Assets] |
|
|
7183
|
+
| **Classification** | [Public / Internal / Confidential / Restricted] |
|
|
7184
|
+
| **Owner** | [Name or role] |
|
|
7185
|
+
| **Created** | YYYY-MM-DD |
|
|
7186
|
+
| **Last Updated** | YYYY-MM-DD |
|
|
7187
|
+
|
|
7188
|
+
## Description
|
|
7189
|
+
|
|
7190
|
+
What data this requirement governs, why it exists, and its significance to the system.
|
|
7191
|
+
|
|
7192
|
+
## Data Model
|
|
7193
|
+
|
|
7194
|
+
Describe the key entities, their attributes, and relationships. Include an entity-relationship summary or reference a diagram.
|
|
7195
|
+
|
|
7196
|
+
| Entity | Key Attributes | Relationships |
|
|
7197
|
+
|---|---|---|
|
|
7198
|
+
| [e.g., User] | [e.g., id, email, name, created_at] | [e.g., Has many Organizations (via membership)] |
|
|
7199
|
+
|
|
7200
|
+
## Data Lifecycle
|
|
7201
|
+
|
|
7202
|
+
| Phase | Description | Duration |
|
|
7203
|
+
|---|---|---|
|
|
7204
|
+
| Creation | [How and when this data is created] | \u2014 |
|
|
7205
|
+
| Active Use | [How this data is used during normal operations] | [e.g., Indefinite while account active] |
|
|
7206
|
+
| Archival | [If/how data is archived after active use] | [e.g., After 12 months of inactivity] |
|
|
7207
|
+
| Deletion | [When and how data is permanently removed] | [e.g., 90 days after account closure] |
|
|
7208
|
+
|
|
7209
|
+
## Retention Policy
|
|
7210
|
+
|
|
7211
|
+
| Data Type | Retention Period | Legal Basis | Deletion Method |
|
|
7212
|
+
|---|---|---|---|
|
|
7213
|
+
| [e.g., User profile data] | [e.g., Account lifetime + 90 days] | [e.g., Contractual obligation] | [e.g., Soft delete \u2192 hard delete after retention] |
|
|
7214
|
+
| [e.g., Audit logs] | [e.g., 7 years] | [e.g., SOC 2 compliance] | [e.g., Automated purge] |
|
|
7215
|
+
|
|
7216
|
+
## Backup & Recovery
|
|
7217
|
+
|
|
7218
|
+
| Parameter | Value |
|
|
7219
|
+
|---|---|
|
|
7220
|
+
| **RPO (Recovery Point Objective)** | [e.g., < 1 hour \u2014 maximum acceptable data loss] |
|
|
7221
|
+
| **RTO (Recovery Time Objective)** | [e.g., < 4 hours \u2014 maximum acceptable downtime] |
|
|
7222
|
+
| **Backup Frequency** | [e.g., Continuous WAL archiving + daily snapshots] |
|
|
7223
|
+
| **Backup Location** | [e.g., Cross-region S3 with encryption] |
|
|
7224
|
+
| **Recovery Testing** | [e.g., Quarterly restore test] |
|
|
7225
|
+
|
|
7226
|
+
## Data Quality Rules
|
|
7227
|
+
|
|
7228
|
+
| Rule | Description | Enforcement |
|
|
7229
|
+
|---|---|---|
|
|
7230
|
+
| [e.g., Email uniqueness] | [e.g., No two active users may share an email] | [e.g., Database unique constraint] |
|
|
7231
|
+
|
|
7232
|
+
## Privacy & Classification
|
|
7233
|
+
|
|
7234
|
+
How this data is classified and what handling rules apply based on that classification.
|
|
7235
|
+
|
|
7236
|
+
| Classification Level | Handling Rules |
|
|
7237
|
+
|---|---|
|
|
7238
|
+
| Public | No restrictions |
|
|
7239
|
+
| Internal | Access controlled, not shared externally |
|
|
7240
|
+
| Confidential | Encrypted at rest, access logged, need-to-know basis |
|
|
7241
|
+
| Restricted | All of Confidential + additional controls per regulation |
|
|
7242
|
+
|
|
7243
|
+
## Traceability
|
|
7244
|
+
|
|
7245
|
+
- **Supports:** [FR-NNN](../functional/FR-NNN-slug.md)
|
|
7246
|
+
- **Protected by:** [SEC-NNN](../security/SEC-NNN-slug.md)
|
|
7247
|
+
- **Stored per:** [TR-NNN](../technical/TR-NNN-slug.md)
|
|
7248
|
+
- **Depends on (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [platform/industry requirement this depends on]
|
|
7249
|
+
- **Enables (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [customer-workflow/consumer-app requirement this enables]
|
|
7250
|
+
|
|
7251
|
+
## Open Items
|
|
7252
|
+
|
|
7253
|
+
### Identified Gaps
|
|
7254
|
+
|
|
7255
|
+
[Document any missing functionality, unhandled edge cases, or incomplete aspects. Number each item and assign a priority (P0/P1/P2/P3). Call out interdependencies with other open items. If none, write "None identified."]
|
|
7256
|
+
|
|
7257
|
+
1. **[Gap title]** \`[P0-P3]\`
|
|
7258
|
+
[Description of what's missing and why it matters.]
|
|
7259
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7260
|
+
|
|
7261
|
+
### Follow-up Questions
|
|
7262
|
+
|
|
7263
|
+
[Document anything ambiguous or where the motivation/reasoning cannot be confidently inferred. Number each item and assign a priority. If none, write "None identified."]
|
|
7264
|
+
|
|
7265
|
+
1. **[Question title]** \`[P0-P3]\`
|
|
7266
|
+
[The question, with context on why the answer matters.]
|
|
7267
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7268
|
+
|
|
7269
|
+
### Contradictions & Inconsistencies
|
|
7270
|
+
|
|
7271
|
+
[Document any conflicts with other requirements, code behavior, or documentation. Number each item and assign a priority. If none, write "None identified."]
|
|
7272
|
+
|
|
7273
|
+
1. **[Contradiction title]** \`[P0-P3]\`
|
|
7274
|
+
[Description of the conflict and what needs to be resolved.]
|
|
7275
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7276
|
+
|
|
7277
|
+
## Revision History
|
|
7278
|
+
|
|
7279
|
+
| Date | Author | Change |
|
|
7280
|
+
|---|---|---|
|
|
7281
|
+
| YYYY-MM-DD | [Name] | Initial draft |
|
|
7282
|
+
`;
|
|
7283
|
+
var TEMPLATE_INT = `---
|
|
7284
|
+
title: "INT-NNN: [Integration Requirement Title]"
|
|
7285
|
+
---
|
|
7286
|
+
|
|
7287
|
+
# INT-NNN: [Integration Requirement Title]
|
|
7288
|
+
|
|
7289
|
+
## Metadata
|
|
7290
|
+
|
|
7291
|
+
| Field | Value |
|
|
7292
|
+
|---|---|
|
|
7293
|
+
| **ID** | INT-NNN |
|
|
7294
|
+
| **Status** | Draft |
|
|
7295
|
+
| **Tier** | [Platform \xB7 Industry \xB7 Customer Workflow \xB7 Consumer Application] |
|
|
7296
|
+
| **Implementor** | [Consortium Member \xB7 Customer \xB7 TBD \u2014 required for Customer Workflow and Consumer Application tiers. When Consortium Member, link to org profile] |
|
|
7297
|
+
| **Customer** | [Link to customer org profile if this requirement originated from or applies to a specific customer. Optional for Platform/Industry tiers, expected for Customer Workflow/Consumer Application tiers] |
|
|
7298
|
+
| **Integration Type** | [REST API / GraphQL / Webhook / Message Queue / File Transfer / SDK] |
|
|
7299
|
+
| **Direction** | [Inbound / Outbound / Bidirectional] |
|
|
7300
|
+
| **External System** | [Name of the third-party or internal system] |
|
|
7301
|
+
| **Owner** | [Name or role] |
|
|
7302
|
+
| **Created** | YYYY-MM-DD |
|
|
7303
|
+
| **Last Updated** | YYYY-MM-DD |
|
|
7304
|
+
|
|
7305
|
+
## Description
|
|
7306
|
+
|
|
7307
|
+
What this integration does, why it's needed, and what business capability it enables.
|
|
7308
|
+
|
|
7309
|
+
## External System Overview
|
|
7310
|
+
|
|
7311
|
+
| Field | Value |
|
|
7312
|
+
|---|---|
|
|
7313
|
+
| **System** | [e.g., Stripe] |
|
|
7314
|
+
| **Purpose** | [e.g., Payment processing and subscription management] |
|
|
7315
|
+
| **API Documentation** | [URL to official docs] |
|
|
7316
|
+
| **API Version** | [e.g., 2023-10-16] |
|
|
7317
|
+
| **Authentication** | [e.g., API key (secret key in header)] |
|
|
7318
|
+
|
|
7319
|
+
## Integration Points
|
|
7320
|
+
|
|
7321
|
+
### [Endpoint/Event 1]: [Name]
|
|
7322
|
+
|
|
7323
|
+
| Field | Value |
|
|
7324
|
+
|---|---|
|
|
7325
|
+
| **Direction** | [Inbound/Outbound] |
|
|
7326
|
+
| **Protocol** | [e.g., HTTPS REST] |
|
|
7327
|
+
| **Endpoint** | [e.g., POST /v1/customers] |
|
|
7328
|
+
| **Authentication** | [e.g., Bearer token] |
|
|
7329
|
+
| **Rate Limit** | [e.g., 100 requests/second] |
|
|
7330
|
+
|
|
7331
|
+
**Request/Payload:**
|
|
7332
|
+
\`\`\`
|
|
7333
|
+
[Brief description or schema reference]
|
|
7334
|
+
\`\`\`
|
|
7335
|
+
|
|
7336
|
+
**Response/Output:**
|
|
7337
|
+
\`\`\`
|
|
7338
|
+
[Brief description or schema reference]
|
|
7339
|
+
\`\`\`
|
|
7340
|
+
|
|
7341
|
+
## Error Handling
|
|
7342
|
+
|
|
7343
|
+
| Error Scenario | Strategy | Retry Policy |
|
|
7344
|
+
|---|---|---|
|
|
7345
|
+
| [e.g., 429 Rate Limited] | [e.g., Exponential backoff] | [e.g., 3 retries, max 30s] |
|
|
7346
|
+
| [e.g., 500 Server Error] | [e.g., Retry with circuit breaker] | [e.g., 3 retries, then circuit open for 60s] |
|
|
7347
|
+
| [e.g., Timeout] | [e.g., Retry once, then dead letter queue] | [e.g., 30s timeout, 1 retry] |
|
|
7348
|
+
|
|
7349
|
+
## Data Mapping
|
|
7350
|
+
|
|
7351
|
+
How data maps between our system and the external system.
|
|
7352
|
+
|
|
7353
|
+
| Our Field | External Field | Transformation |
|
|
7354
|
+
|---|---|---|
|
|
7355
|
+
| [e.g., user.email] | [e.g., customer.email] | [e.g., Direct mapping] |
|
|
7356
|
+
|
|
7357
|
+
## SLA & Availability
|
|
7358
|
+
|
|
7359
|
+
| Parameter | Our Expectation | External System's Published SLA |
|
|
7360
|
+
|---|---|---|
|
|
7361
|
+
| Availability | [e.g., 99.9%] | [e.g., 99.99%] |
|
|
7362
|
+
| Response Time | [e.g., < 500ms p99] | [e.g., < 200ms typical] |
|
|
7363
|
+
|
|
7364
|
+
## Fallback Behavior
|
|
7365
|
+
|
|
7366
|
+
What happens when this integration is unavailable. How does the system degrade gracefully?
|
|
7367
|
+
|
|
7368
|
+
## Testing Strategy
|
|
7369
|
+
|
|
7370
|
+
| Environment | Approach |
|
|
7371
|
+
|---|---|
|
|
7372
|
+
| Development | [e.g., Mock server / sandbox environment] |
|
|
7373
|
+
| Staging | [e.g., Sandbox API with test credentials] |
|
|
7374
|
+
| Production | [e.g., Live API with monitoring] |
|
|
7375
|
+
|
|
7376
|
+
## Traceability
|
|
7377
|
+
|
|
7378
|
+
- **Enables:** [FR-NNN](../functional/FR-NNN-slug.md)
|
|
7379
|
+
- **Constrained by:** [NFR-NNN](../non-functional/NFR-NNN-slug.md)
|
|
7380
|
+
- **Secured by:** [SEC-NNN](../security/SEC-NNN-slug.md)
|
|
7381
|
+
- **Depends on (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [platform/industry requirement this depends on]
|
|
7382
|
+
- **Enables (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [customer-workflow/consumer-app requirement this enables]
|
|
7383
|
+
|
|
7384
|
+
## Open Items
|
|
7385
|
+
|
|
7386
|
+
### Identified Gaps
|
|
7387
|
+
|
|
7388
|
+
[Document any missing functionality, unhandled edge cases, or incomplete aspects. Number each item and assign a priority (P0/P1/P2/P3). Call out interdependencies with other open items. If none, write "None identified."]
|
|
7389
|
+
|
|
7390
|
+
1. **[Gap title]** \`[P0-P3]\`
|
|
7391
|
+
[Description of what's missing and why it matters.]
|
|
7392
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7393
|
+
|
|
7394
|
+
### Follow-up Questions
|
|
7395
|
+
|
|
7396
|
+
[Document anything ambiguous or where the motivation/reasoning cannot be confidently inferred. Number each item and assign a priority. If none, write "None identified."]
|
|
7397
|
+
|
|
7398
|
+
1. **[Question title]** \`[P0-P3]\`
|
|
7399
|
+
[The question, with context on why the answer matters.]
|
|
7400
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7401
|
+
|
|
7402
|
+
### Contradictions & Inconsistencies
|
|
7403
|
+
|
|
7404
|
+
[Document any conflicts with other requirements, code behavior, or documentation. Number each item and assign a priority. If none, write "None identified."]
|
|
7405
|
+
|
|
7406
|
+
1. **[Contradiction title]** \`[P0-P3]\`
|
|
7407
|
+
[Description of the conflict and what needs to be resolved.]
|
|
7408
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7409
|
+
|
|
7410
|
+
## Revision History
|
|
7411
|
+
|
|
7412
|
+
| Date | Author | Change |
|
|
7413
|
+
|---|---|---|
|
|
7414
|
+
| YYYY-MM-DD | [Name] | Initial draft |
|
|
7415
|
+
`;
|
|
7416
|
+
var TEMPLATE_OPS = `---
|
|
7417
|
+
title: "OPS-NNN: [Operational Requirement Title]"
|
|
7418
|
+
---
|
|
7419
|
+
|
|
7420
|
+
# OPS-NNN: [Operational Requirement Title]
|
|
7421
|
+
|
|
7422
|
+
## Metadata
|
|
7423
|
+
|
|
7424
|
+
| Field | Value |
|
|
7425
|
+
|---|---|
|
|
7426
|
+
| **ID** | OPS-NNN |
|
|
7427
|
+
| **Status** | Draft |
|
|
7428
|
+
| **Tier** | [Platform \xB7 Industry \xB7 Customer Workflow \xB7 Consumer Application] |
|
|
7429
|
+
| **Implementor** | [Consortium Member \xB7 Customer \xB7 TBD \u2014 required for Customer Workflow and Consumer Application tiers. When Consortium Member, link to org profile] |
|
|
7430
|
+
| **Customer** | [Link to customer org profile if this requirement originated from or applies to a specific customer. Optional for Platform/Industry tiers, expected for Customer Workflow/Consumer Application tiers] |
|
|
7431
|
+
| **Operations Domain** | [Deployment / Monitoring / Alerting / Logging / Incident Response / Backup] |
|
|
7432
|
+
| **Owner** | [Name or role] |
|
|
7433
|
+
| **Created** | YYYY-MM-DD |
|
|
7434
|
+
| **Last Updated** | YYYY-MM-DD |
|
|
7435
|
+
|
|
7436
|
+
## Description
|
|
7437
|
+
|
|
7438
|
+
What operational concern this requirement addresses and why it matters for system reliability.
|
|
7439
|
+
|
|
7440
|
+
## Current State
|
|
7441
|
+
|
|
7442
|
+
If this applies to an existing system, document the current operational posture.
|
|
7443
|
+
|
|
7444
|
+
## Requirements
|
|
7445
|
+
|
|
7446
|
+
### Deployment
|
|
7447
|
+
|
|
7448
|
+
| Parameter | Requirement |
|
|
7449
|
+
|---|---|
|
|
7450
|
+
| **Strategy** | [e.g., Blue-green / Rolling / Canary] |
|
|
7451
|
+
| **Frequency** | [e.g., On-demand, multiple times per day] |
|
|
7452
|
+
| **Rollback** | [e.g., Automated rollback on health check failure within 5 minutes] |
|
|
7453
|
+
| **Downtime** | [e.g., Zero-downtime required] |
|
|
7454
|
+
|
|
7455
|
+
### Monitoring & Observability
|
|
7456
|
+
|
|
7457
|
+
| Signal Type | What to Monitor | Tool | Retention |
|
|
7458
|
+
|---|---|---|---|
|
|
7459
|
+
| **Metrics** | [e.g., Request rate, error rate, latency p50/p95/p99] | [e.g., Datadog] | [e.g., 15 months] |
|
|
7460
|
+
| **Logs** | [e.g., Application logs, access logs, audit logs] | [e.g., CloudWatch \u2192 S3] | [e.g., 90 days hot, 1 year cold] |
|
|
7461
|
+
| **Traces** | [e.g., Distributed request traces] | [e.g., Datadog APM] | [e.g., 30 days] |
|
|
7462
|
+
|
|
7463
|
+
### Alerting
|
|
7464
|
+
|
|
7465
|
+
| Alert | Condition | Severity | Notification Channel | Escalation |
|
|
7466
|
+
|---|---|---|---|---|
|
|
7467
|
+
| [e.g., High error rate] | [e.g., 5xx rate > 1% for 5 min] | [e.g., P1 / Critical] | [e.g., PagerDuty \u2192 on-call] | [e.g., If unack'd in 15 min \u2192 engineering lead] |
|
|
7468
|
+
|
|
7469
|
+
### Incident Response
|
|
7470
|
+
|
|
7471
|
+
| Severity | Response Time | Resolution Target | Communication |
|
|
7472
|
+
|---|---|---|---|
|
|
7473
|
+
| P1 (Critical) | [e.g., 15 minutes] | [e.g., 1 hour] | [e.g., Status page + stakeholder notification] |
|
|
7474
|
+
| P2 (Major) | [e.g., 30 minutes] | [e.g., 4 hours] | [e.g., Status page if customer-facing] |
|
|
7475
|
+
| P3 (Minor) | [e.g., Next business day] | [e.g., 5 business days] | [e.g., Internal tracking only] |
|
|
7476
|
+
|
|
7477
|
+
## Runbook References
|
|
7478
|
+
|
|
7479
|
+
| Scenario | Runbook Location |
|
|
7480
|
+
|---|---|
|
|
7481
|
+
| [e.g., Database failover] | [Link or path] |
|
|
7482
|
+
| [e.g., High memory usage] | [Link or path] |
|
|
7483
|
+
|
|
7484
|
+
## Environments
|
|
7485
|
+
|
|
7486
|
+
| Environment | Purpose | Infrastructure | Access |
|
|
7487
|
+
|---|---|---|---|
|
|
7488
|
+
| Development | [Local development] | [e.g., Docker Compose] | [e.g., All developers] |
|
|
7489
|
+
| Staging | [Pre-production testing] | [e.g., AWS, scaled down] | [e.g., Engineering team] |
|
|
7490
|
+
| Production | [Live system] | [e.g., AWS, full scale] | [e.g., Restricted, via bastion] |
|
|
7491
|
+
|
|
7492
|
+
## Traceability
|
|
7493
|
+
|
|
7494
|
+
- **Monitors:** [NFR-NNN](../non-functional/NFR-NNN-slug.md)
|
|
7495
|
+
- **Supports:** [BR-NNN](../business/BR-NNN-slug.md)
|
|
7496
|
+
- **Uses:** [TR-NNN](../technical/TR-NNN-slug.md)
|
|
7497
|
+
- **Depends on (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [platform/industry requirement this depends on]
|
|
7498
|
+
- **Enables (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [customer-workflow/consumer-app requirement this enables]
|
|
7499
|
+
|
|
7500
|
+
## Open Items
|
|
7501
|
+
|
|
7502
|
+
### Identified Gaps
|
|
7503
|
+
|
|
7504
|
+
[Document any missing functionality, unhandled edge cases, or incomplete aspects. Number each item and assign a priority (P0/P1/P2/P3). Call out interdependencies with other open items. If none, write "None identified."]
|
|
7505
|
+
|
|
7506
|
+
1. **[Gap title]** \`[P0-P3]\`
|
|
7507
|
+
[Description of what's missing and why it matters.]
|
|
7508
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7509
|
+
|
|
7510
|
+
### Follow-up Questions
|
|
7511
|
+
|
|
7512
|
+
[Document anything ambiguous or where the motivation/reasoning cannot be confidently inferred. Number each item and assign a priority. If none, write "None identified."]
|
|
7513
|
+
|
|
7514
|
+
1. **[Question title]** \`[P0-P3]\`
|
|
7515
|
+
[The question, with context on why the answer matters.]
|
|
7516
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7517
|
+
|
|
7518
|
+
### Contradictions & Inconsistencies
|
|
7519
|
+
|
|
7520
|
+
[Document any conflicts with other requirements, code behavior, or documentation. Number each item and assign a priority. If none, write "None identified."]
|
|
7521
|
+
|
|
7522
|
+
1. **[Contradiction title]** \`[P0-P3]\`
|
|
7523
|
+
[Description of the conflict and what needs to be resolved.]
|
|
7524
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7525
|
+
|
|
7526
|
+
## Revision History
|
|
7527
|
+
|
|
7528
|
+
| Date | Author | Change |
|
|
7529
|
+
|---|---|---|
|
|
7530
|
+
| YYYY-MM-DD | [Name] | Initial draft |
|
|
7531
|
+
`;
|
|
7532
|
+
var TEMPLATE_UX = `---
|
|
7533
|
+
title: "UX-NNN: [UX Requirement Title]"
|
|
7534
|
+
---
|
|
7535
|
+
|
|
7536
|
+
# UX-NNN: [UX Requirement Title]
|
|
7537
|
+
|
|
7538
|
+
## Metadata
|
|
7539
|
+
|
|
7540
|
+
| Field | Value |
|
|
7541
|
+
|---|---|
|
|
7542
|
+
| **ID** | UX-NNN |
|
|
7543
|
+
| **Status** | Draft |
|
|
7544
|
+
| **Tier** | [Platform \xB7 Industry \xB7 Customer Workflow \xB7 Consumer Application] |
|
|
7545
|
+
| **Implementor** | [Consortium Member \xB7 Customer \xB7 TBD \u2014 required for Customer Workflow and Consumer Application tiers. When Consortium Member, link to org profile] |
|
|
7546
|
+
| **Customer** | [Link to customer org profile if this requirement originated from or applies to a specific customer. Optional for Platform/Industry tiers, expected for Customer Workflow/Consumer Application tiers] |
|
|
7547
|
+
| **UX Domain** | [Accessibility / Responsiveness / Internationalization / Interaction Design / Information Architecture] |
|
|
7548
|
+
| **Priority** | [Critical / High / Medium / Low] |
|
|
7549
|
+
| **Owner** | [Name or role] |
|
|
7550
|
+
| **Created** | YYYY-MM-DD |
|
|
7551
|
+
| **Last Updated** | YYYY-MM-DD |
|
|
7552
|
+
|
|
7553
|
+
## Description
|
|
7554
|
+
|
|
7555
|
+
What user experience concern this requirement addresses and why it matters.
|
|
7556
|
+
|
|
7557
|
+
## Target Users
|
|
7558
|
+
|
|
7559
|
+
| User Segment | Characteristics | Key Needs |
|
|
7560
|
+
|---|---|---|
|
|
7561
|
+
| [e.g., Power users] | [e.g., Daily usage, keyboard-heavy workflow] | [e.g., Keyboard shortcuts, bulk actions] |
|
|
7562
|
+
|
|
7563
|
+
## Accessibility
|
|
7564
|
+
|
|
7565
|
+
| Parameter | Requirement |
|
|
7566
|
+
|---|---|
|
|
7567
|
+
| **WCAG Level** | [e.g., 2.1 Level AA] |
|
|
7568
|
+
| **Screen Reader Support** | [e.g., ARIA labels on all interactive elements] |
|
|
7569
|
+
| **Keyboard Navigation** | [e.g., All functionality accessible via keyboard] |
|
|
7570
|
+
| **Color Contrast** | [e.g., Minimum 4.5:1 for normal text, 3:1 for large text] |
|
|
7571
|
+
| **Motion** | [e.g., Respect prefers-reduced-motion; no auto-playing animations] |
|
|
7572
|
+
|
|
7573
|
+
## Responsive Design
|
|
7574
|
+
|
|
7575
|
+
| Breakpoint | Target Devices | Layout Behavior |
|
|
7576
|
+
|---|---|---|
|
|
7577
|
+
| [e.g., < 375px] | [e.g., Small phones] | [e.g., Single column, stacked navigation] |
|
|
7578
|
+
| [e.g., 375\u2013768px] | [e.g., Phones, small tablets] | [e.g., Single column, hamburger menu] |
|
|
7579
|
+
| [e.g., 768\u20131024px] | [e.g., Tablets] | [e.g., Two-column where appropriate] |
|
|
7580
|
+
| [e.g., > 1024px] | [e.g., Desktop] | [e.g., Full layout with sidebar navigation] |
|
|
7581
|
+
|
|
7582
|
+
## Internationalization (i18n)
|
|
7583
|
+
|
|
7584
|
+
| Parameter | Requirement |
|
|
7585
|
+
|---|---|
|
|
7586
|
+
| **Supported Languages** | [e.g., English (launch), Spanish, French (Phase 2)] |
|
|
7587
|
+
| **Text Direction** | [e.g., LTR only at launch; RTL support in backlog] |
|
|
7588
|
+
| **Date/Time Formats** | [e.g., Locale-aware formatting] |
|
|
7589
|
+
| **Currency** | [e.g., Display in user's locale, store in USD] |
|
|
7590
|
+
|
|
7591
|
+
## Interaction Patterns
|
|
7592
|
+
|
|
7593
|
+
Key interaction patterns and principles that apply to this requirement.
|
|
7594
|
+
|
|
7595
|
+
| Pattern | Standard | Notes |
|
|
7596
|
+
|---|---|---|
|
|
7597
|
+
| [e.g., Form validation] | [e.g., Inline validation on blur, summary on submit] | [e.g., Error messages adjacent to field] |
|
|
7598
|
+
| [e.g., Loading states] | [e.g., Skeleton screens for content, spinners for actions] | [e.g., No blank screens during loads] |
|
|
7599
|
+
|
|
7600
|
+
## Design System Reference
|
|
7601
|
+
|
|
7602
|
+
Reference to the project's design system, component library, or style guide if one exists.
|
|
7603
|
+
|
|
7604
|
+
## Acceptance Criteria
|
|
7605
|
+
|
|
7606
|
+
- [ ] [Specific, verifiable UX condition]
|
|
7607
|
+
- [ ] [e.g., All pages score \u2265 90 on Lighthouse accessibility audit]
|
|
7608
|
+
- [ ] [e.g., All interactive elements have visible focus indicators]
|
|
7609
|
+
|
|
7610
|
+
## Traceability
|
|
7611
|
+
|
|
7612
|
+
- **Enhances:** [FR-NNN](../functional/FR-NNN-slug.md)
|
|
7613
|
+
- **Constrained by:** [NFR-NNN](../non-functional/NFR-NNN-slug.md)
|
|
7614
|
+
- **Supports:** [BR-NNN](../business/BR-NNN-slug.md)
|
|
7615
|
+
- **Depends on (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [platform/industry requirement this depends on]
|
|
7616
|
+
- **Enables (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [customer-workflow/consumer-app requirement this enables]
|
|
7617
|
+
|
|
7618
|
+
## Open Items
|
|
7619
|
+
|
|
7620
|
+
### Identified Gaps
|
|
7621
|
+
|
|
7622
|
+
[Document any missing functionality, unhandled edge cases, or incomplete aspects. Number each item and assign a priority (P0/P1/P2/P3). Call out interdependencies with other open items. If none, write "None identified."]
|
|
7623
|
+
|
|
7624
|
+
1. **[Gap title]** \`[P0-P3]\`
|
|
7625
|
+
[Description of what's missing and why it matters.]
|
|
7626
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7627
|
+
|
|
7628
|
+
### Follow-up Questions
|
|
7629
|
+
|
|
7630
|
+
[Document anything ambiguous or where the motivation/reasoning cannot be confidently inferred. Number each item and assign a priority. If none, write "None identified."]
|
|
7631
|
+
|
|
7632
|
+
1. **[Question title]** \`[P0-P3]\`
|
|
7633
|
+
[The question, with context on why the answer matters.]
|
|
7634
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7635
|
+
|
|
7636
|
+
### Contradictions & Inconsistencies
|
|
7637
|
+
|
|
7638
|
+
[Document any conflicts with other requirements, code behavior, or documentation. Number each item and assign a priority. If none, write "None identified."]
|
|
7639
|
+
|
|
7640
|
+
1. **[Contradiction title]** \`[P0-P3]\`
|
|
7641
|
+
[Description of the conflict and what needs to be resolved.]
|
|
7642
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7643
|
+
|
|
7644
|
+
## Revision History
|
|
7645
|
+
|
|
7646
|
+
| Date | Author | Change |
|
|
7647
|
+
|---|---|---|
|
|
7648
|
+
| YYYY-MM-DD | [Name] | Initial draft |
|
|
7649
|
+
`;
|
|
7650
|
+
var TEMPLATE_MT = `---
|
|
7651
|
+
title: "MT-NNN: [Multi-Tenancy Requirement Title]"
|
|
7652
|
+
---
|
|
7653
|
+
|
|
7654
|
+
# MT-NNN: [Multi-Tenancy Requirement Title]
|
|
7655
|
+
|
|
7656
|
+
## Metadata
|
|
7657
|
+
|
|
7658
|
+
| Field | Value |
|
|
7659
|
+
|---|---|
|
|
7660
|
+
| **ID** | MT-NNN |
|
|
7661
|
+
| **Status** | Draft |
|
|
7662
|
+
| **Tier** | [Platform \xB7 Industry \xB7 Customer Workflow \xB7 Consumer Application] |
|
|
7663
|
+
| **Implementor** | [Consortium Member \xB7 Customer \xB7 TBD \u2014 required for Customer Workflow and Consumer Application tiers. When Consortium Member, link to org profile] |
|
|
7664
|
+
| **Customer** | [Link to customer org profile if this requirement originated from or applies to a specific customer. Optional for Platform/Industry tiers, expected for Customer Workflow/Consumer Application tiers] |
|
|
7665
|
+
| **MT Domain** | [Tenant Isolation / Feature Gating / Usage Metering / Billing / Provisioning / Licensing] |
|
|
7666
|
+
| **Priority** | [Critical / High / Medium / Low] |
|
|
7667
|
+
| **Owner** | [Name or role] |
|
|
7668
|
+
| **Created** | YYYY-MM-DD |
|
|
7669
|
+
| **Last Updated** | YYYY-MM-DD |
|
|
7670
|
+
|
|
7671
|
+
## Description
|
|
7672
|
+
|
|
7673
|
+
What multi-tenancy concern this requirement addresses and why it matters for the SaaS product.
|
|
7674
|
+
|
|
7675
|
+
## Tenant Isolation Model
|
|
7676
|
+
|
|
7677
|
+
| Layer | Isolation Strategy | Details |
|
|
7678
|
+
|---|---|---|
|
|
7679
|
+
| **Database** | [e.g., Row-level / Schema-per-tenant / Database-per-tenant] | [e.g., tenant_id column on all tenant-scoped tables, enforced by RLS] |
|
|
7680
|
+
| **Application** | [e.g., Shared application, tenant context from auth token] | [e.g., Middleware extracts tenant from JWT, injects into query context] |
|
|
7681
|
+
| **Infrastructure** | [e.g., Shared infrastructure / Dedicated compute per tenant] | [e.g., Shared at launch, dedicated option for enterprise tier] |
|
|
7682
|
+
| **Storage** | [e.g., Shared bucket with tenant prefix / Separate buckets] | [e.g., S3 bucket with tenant-id/ prefix, IAM policies per tenant] |
|
|
7683
|
+
|
|
7684
|
+
## Feature Gating
|
|
7685
|
+
|
|
7686
|
+
| Feature | Free Tier | Pro Tier | Enterprise Tier |
|
|
7687
|
+
|---|---|---|---|
|
|
7688
|
+
| [e.g., Number of users] | [e.g., Up to 5] | [e.g., Up to 50] | [e.g., Unlimited] |
|
|
7689
|
+
| [e.g., API access] | [e.g., No] | [e.g., Yes, 1000 calls/day] | [e.g., Yes, unlimited] |
|
|
7690
|
+
|
|
7691
|
+
### Gating Mechanism
|
|
7692
|
+
|
|
7693
|
+
How feature gates are implemented and managed (e.g., feature flag service, plan-based checks, entitlement system).
|
|
7694
|
+
|
|
7695
|
+
## Usage Metering
|
|
7696
|
+
|
|
7697
|
+
| Dimension | Unit | Collection Method | Billing Cycle |
|
|
7698
|
+
|---|---|---|---|
|
|
7699
|
+
| [e.g., API calls] | [e.g., Per request] | [e.g., API gateway counter] | [e.g., Monthly] |
|
|
7700
|
+
| [e.g., Storage] | [e.g., GB-month] | [e.g., Nightly calculation] | [e.g., Monthly] |
|
|
7701
|
+
|
|
7702
|
+
## Tenant Provisioning
|
|
7703
|
+
|
|
7704
|
+
| Step | Action | Duration | Automated? |
|
|
7705
|
+
|---|---|---|---|
|
|
7706
|
+
| 1 | [e.g., Create tenant record] | [e.g., < 1s] | [e.g., Yes] |
|
|
7707
|
+
| 2 | [e.g., Provision database schema/rows] | [e.g., < 5s] | [e.g., Yes] |
|
|
7708
|
+
| 3 | [e.g., Configure DNS/subdomain] | [e.g., < 1 min] | [e.g., Yes] |
|
|
7709
|
+
|
|
7710
|
+
## Tenant Offboarding
|
|
7711
|
+
|
|
7712
|
+
What happens when a tenant leaves \u2014 data retention, export, cleanup procedures.
|
|
7713
|
+
|
|
7714
|
+
## Noisy Neighbor Prevention
|
|
7715
|
+
|
|
7716
|
+
How the system prevents one tenant from degrading the experience of others.
|
|
7717
|
+
|
|
7718
|
+
| Strategy | Implementation |
|
|
7719
|
+
|---|---|
|
|
7720
|
+
| [e.g., Rate limiting] | [e.g., Per-tenant rate limits at API gateway] |
|
|
7721
|
+
| [e.g., Resource quotas] | [e.g., Max storage per tenant per tier] |
|
|
7722
|
+
|
|
7723
|
+
## Acceptance Criteria
|
|
7724
|
+
|
|
7725
|
+
- [ ] [e.g., Tenant A cannot access Tenant B's data under any circumstances]
|
|
7726
|
+
- [ ] [e.g., Feature gate changes take effect within 60 seconds]
|
|
7727
|
+
- [ ] [e.g., New tenant provisioning completes in under 30 seconds]
|
|
7728
|
+
|
|
7729
|
+
## Traceability
|
|
7730
|
+
|
|
7731
|
+
- **Implements:** [BR-NNN](../business/BR-NNN-slug.md)
|
|
7732
|
+
- **Secured by:** [SEC-NNN](../security/SEC-NNN-slug.md)
|
|
7733
|
+
- **Constrained by:** [NFR-NNN](../non-functional/NFR-NNN-slug.md)
|
|
7734
|
+
- **Depends on (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [platform/industry requirement this depends on]
|
|
7735
|
+
- **Enables (cross-tier):** [XX-NNN](../category/XX-NNN-slug.md) \u2014 [customer-workflow/consumer-app requirement this enables]
|
|
7736
|
+
|
|
7737
|
+
## Open Items
|
|
7738
|
+
|
|
7739
|
+
### Identified Gaps
|
|
7740
|
+
|
|
7741
|
+
[Document any missing functionality, unhandled edge cases, or incomplete aspects. Number each item and assign a priority (P0/P1/P2/P3). Call out interdependencies with other open items. If none, write "None identified."]
|
|
7742
|
+
|
|
7743
|
+
1. **[Gap title]** \`[P0-P3]\`
|
|
7744
|
+
[Description of what's missing and why it matters.]
|
|
7745
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7746
|
+
|
|
7747
|
+
### Follow-up Questions
|
|
7748
|
+
|
|
7749
|
+
[Document anything ambiguous or where the motivation/reasoning cannot be confidently inferred. Number each item and assign a priority. If none, write "None identified."]
|
|
7750
|
+
|
|
7751
|
+
1. **[Question title]** \`[P0-P3]\`
|
|
7752
|
+
[The question, with context on why the answer matters.]
|
|
7753
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7754
|
+
|
|
7755
|
+
### Contradictions & Inconsistencies
|
|
7756
|
+
|
|
7757
|
+
[Document any conflicts with other requirements, code behavior, or documentation. Number each item and assign a priority. If none, write "None identified."]
|
|
7758
|
+
|
|
7759
|
+
1. **[Contradiction title]** \`[P0-P3]\`
|
|
7760
|
+
[Description of the conflict and what needs to be resolved.]
|
|
7761
|
+
\u2192 [Depends on / Blocks]: [XX-NNN Open Item #N](../category/XX-NNN-slug.md#open-items) (if applicable)
|
|
7762
|
+
|
|
7763
|
+
## Revision History
|
|
7764
|
+
|
|
7765
|
+
| Date | Author | Change |
|
|
7766
|
+
|---|---|---|
|
|
7767
|
+
| YYYY-MM-DD | [Name] | Initial draft |
|
|
7768
|
+
`;
|
|
7769
|
+
var TEMPLATE_CATEGORY_README = `# [Category Name] Requirements
|
|
7770
|
+
|
|
7771
|
+
## Purpose
|
|
7772
|
+
|
|
7773
|
+
[One-paragraph description of what belongs in this category and the question it answers.]
|
|
7774
|
+
|
|
7775
|
+
## What Belongs Here
|
|
7776
|
+
|
|
7777
|
+
- [Type of requirement 1]
|
|
7778
|
+
- [Type of requirement 2]
|
|
7779
|
+
- [Type of requirement 3]
|
|
7780
|
+
|
|
7781
|
+
## What Does NOT Belong Here
|
|
7782
|
+
|
|
7783
|
+
| If your requirement looks like... | It probably belongs in... | Why |
|
|
7784
|
+
|---|---|---|
|
|
7785
|
+
| [e.g., "The system must respond in < 200ms"] | [e.g., NFR (Non-Functional)] | [e.g., That's a quality/performance target, not a feature description] |
|
|
7786
|
+
|
|
7787
|
+
## Template
|
|
7788
|
+
|
|
7789
|
+
Use [\`_template-{PREFIX}.md\`](../templates/_template-{PREFIX}.md) for all new documents in this category.
|
|
7790
|
+
|
|
7791
|
+
## Current Documents
|
|
7792
|
+
|
|
7793
|
+
| ID | Title | Status | Last Updated |
|
|
7794
|
+
|---|---|---|---|
|
|
7795
|
+
| [{PREFIX}-001](/{PREFIX}-001-slug.md) | [Title] | [Status] | [Date] |
|
|
7796
|
+
|
|
7797
|
+
## Conventions
|
|
7798
|
+
|
|
7799
|
+
- File naming: \`{PREFIX}-NNN-descriptive-slug.md\`
|
|
7800
|
+
- Number sequentially \u2014 check the table above for the next available number
|
|
7801
|
+
- Every document must include YAML frontmatter with a \`title\` field
|
|
7802
|
+
- Every document must include a \`## Traceability\` section
|
|
7803
|
+
`;
|
|
7804
|
+
var TEMPLATE_REQUIREMENTS_README = `---
|
|
7805
|
+
title: "[Project Name] \u2014 Requirements Documentation"
|
|
7806
|
+
---
|
|
7807
|
+
|
|
7808
|
+
# [Project Name] \u2014 Requirements Documentation
|
|
7809
|
+
|
|
7810
|
+
This directory contains the structured requirements taxonomy for [Project Name]. It covers the full lifecycle from business intent through operational concerns, providing traceability between strategic goals and implementation work.
|
|
7811
|
+
|
|
7812
|
+
## Taxonomy Overview
|
|
7813
|
+
|
|
7814
|
+
| Category | Prefix | Directory | Purpose |
|
|
7815
|
+
|---|---|---|---|
|
|
7816
|
+
| Business Requirements | BR | [\`business/\`](business/README.md) | Strategic intent, stakeholders, success metrics |
|
|
7817
|
+
| Functional Requirements | FR | [\`functional/\`](functional/README.md) | User stories, flows, acceptance criteria |
|
|
7818
|
+
| Non-Functional Requirements | NFR | [\`non-functional/\`](non-functional/README.md) | Performance, scalability, availability targets |
|
|
7819
|
+
| Technical Requirements | TR | [\`technical/\`](technical/README.md) | Technology choices, framework decisions |
|
|
7820
|
+
| Architectural Decisions | ADR | [\`architectural-decisions/\`](architectural-decisions/README.md) | Context, decision, consequences (standard ADR format) |
|
|
7821
|
+
| Security & Compliance | SEC | [\`security/\`](security/README.md) | Auth, encryption, audit, regulatory |
|
|
7822
|
+
| Data Requirements | DR | [\`data/\`](data/README.md) | Data models, retention, classification, RPO/RTO |
|
|
7823
|
+
| Integration Requirements | INT | [\`integration/\`](integration/README.md) | APIs, third-party systems, protocols |
|
|
7824
|
+
| Operational Requirements | OPS | [\`operational/\`](operational/README.md) | Deployment, monitoring, alerting, logging |
|
|
7825
|
+
| UX Requirements | UX | [\`ux/\`](ux/README.md) | Accessibility, responsiveness, i18n |
|
|
7826
|
+
| Multi-Tenancy & Licensing | MT | [\`multi-tenancy/\`](multi-tenancy/README.md) | Tenant isolation, feature gating, billing |
|
|
7827
|
+
|
|
7828
|
+
Each directory contains a \`README.md\` with detailed guidance on what belongs in that category (and what doesn't), common disambiguation tips, and project-specific context. When unsure where a requirement belongs, start with the category README.
|
|
7829
|
+
|
|
7830
|
+
## Which Category Do I Use?
|
|
7831
|
+
|
|
7832
|
+
When capturing or decomposing a requirement, use the question it answers to determine the correct category:
|
|
7833
|
+
|
|
7834
|
+
| Question | Category | Example |
|
|
7835
|
+
|---|---|---|
|
|
7836
|
+
| **Why** do we need this? What business value does it deliver? | BR | "We need self-service registration to reduce sales-assisted onboarding costs" |
|
|
7837
|
+
| **What** does the system do? What is the user-visible behavior? | FR | "A user can register with email and password and receive a verification link" |
|
|
7838
|
+
| **How well** must the system perform? What quality bar must it meet? | NFR | "Registration API must respond within 200ms at p99" |
|
|
7839
|
+
| **What technology** are we choosing, and why that one? | TR | "PostgreSQL 16+ for the primary datastore" |
|
|
7840
|
+
| **What structural decision** are we making, and what are the trade-offs? | ADR | "Use row-level tenant isolation rather than schema-per-tenant" |
|
|
7841
|
+
| **What must we protect**, and what rules govern that protection? | SEC | "All PII must be encrypted at rest; SOC 2 Type II compliance required" |
|
|
7842
|
+
| **What data** do we store, for how long, and how do we recover it? | DR | "Tenant data retained for 90 days after account closure, RPO < 1 hour" |
|
|
7843
|
+
| **What external systems** do we connect to, and how? | INT | "Stripe Billing API for subscription management via REST" |
|
|
7844
|
+
| **How do we deploy, monitor, and respond** to incidents? | OPS | "Blue-green deployments with PagerDuty alerting on error rate > 1%" |
|
|
7845
|
+
| **How must the interface look, feel, and behave** for users? | UX | "WCAG 2.1 AA compliance; responsive down to 375px width" |
|
|
7846
|
+
| **How do we isolate tenants, gate features, and meter usage?** | MT | "Logical tenant isolation at row level; API call metering per plan tier" |
|
|
7847
|
+
|
|
7848
|
+
### Common Disambiguation
|
|
7849
|
+
|
|
7850
|
+
- **SEC vs NFR:** If it's about protecting data, enforcing access control, or meeting a regulation \u2192 SEC. If it's about system performance, uptime, or scalability \u2192 NFR. A requirement like "99.9% uptime" is an NFR; "audit logs for all admin actions" is SEC.
|
|
7851
|
+
- **TR vs ADR:** A TR specifies a concrete technology choice ("use PostgreSQL"). An ADR records a structural decision with context, trade-offs, and alternatives considered ("why row-level isolation over schema-per-tenant"). TRs often follow from ADRs.
|
|
7852
|
+
- **FR vs INT:** If it describes what the user experiences \u2192 FR. If it describes how two systems communicate \u2192 INT. "User can pay with a credit card" is FR; "Stripe Checkout API integration for payment processing" is INT.
|
|
7853
|
+
- **DR vs SEC:** If it's about what data exists, how long we keep it, and how we recover it \u2192 DR. If it's about who can access it and how it's protected \u2192 SEC. These often cross-reference each other.
|
|
7854
|
+
- **NFR vs OPS:** If it's a measurable target the system must meet \u2192 NFR. If it's about the tooling and processes to run the system \u2192 OPS. "p99 latency < 200ms" is NFR; "Datadog APM for latency monitoring" is OPS.
|
|
7855
|
+
|
|
7856
|
+
## File Naming Convention
|
|
7857
|
+
|
|
7858
|
+
\`\`\`
|
|
7859
|
+
{PREFIX}-{NNN}-{slug}.md
|
|
7860
|
+
\`\`\`
|
|
7861
|
+
|
|
7862
|
+
- **PREFIX** \u2014 category abbreviation from the table above
|
|
7863
|
+
- **NNN** \u2014 three-digit sequential number (e.g., \`001\`, \`012\`)
|
|
7864
|
+
- **slug** \u2014 lowercase kebab-case descriptive name
|
|
7865
|
+
|
|
7866
|
+
Examples:
|
|
7867
|
+
- \`FR-001-user-registration.md\`
|
|
7868
|
+
- \`SEC-001-multi-tenant-auth.md\`
|
|
7869
|
+
- \`ADR-001-database-selection.md\`
|
|
7870
|
+
|
|
7871
|
+
## Status Definitions
|
|
7872
|
+
|
|
7873
|
+
All requirements use a universal status lifecycle:
|
|
7874
|
+
|
|
7875
|
+
| Status | Meaning |
|
|
7876
|
+
|---|---|
|
|
7877
|
+
| \`Draft\` | Initial capture, under discussion |
|
|
7878
|
+
| \`Proposed\` | Formally proposed, awaiting review |
|
|
7879
|
+
| \`Accepted\` | Approved and active |
|
|
7880
|
+
| \`Implemented\` | Fully delivered |
|
|
7881
|
+
| \`Deprecated\` | No longer applicable |
|
|
7882
|
+
| \`Superseded\` | Replaced by another requirement (link to successor) |
|
|
7883
|
+
|
|
7884
|
+
## Cross-Referencing Guide
|
|
7885
|
+
|
|
7886
|
+
Every requirement document should include a \`## Traceability\` section. Use relative markdown links with the requirement ID as link text.
|
|
7887
|
+
|
|
7888
|
+
Example:
|
|
7889
|
+
\`\`\`markdown
|
|
7890
|
+
## Traceability
|
|
7891
|
+
|
|
7892
|
+
- **Implements:** [FR-001](../functional/FR-001-user-registration.md)
|
|
7893
|
+
- **Constrained by:** [NFR-001](../non-functional/NFR-001-uptime-sla.md)
|
|
7894
|
+
- **Related:** [SEC-001](../security/SEC-001-multi-tenant-auth.md)
|
|
7895
|
+
\`\`\`
|
|
7896
|
+
|
|
7897
|
+
### Link Types
|
|
7898
|
+
|
|
7899
|
+
| Link Type | Meaning |
|
|
7900
|
+
|---|---|
|
|
7901
|
+
| **Implements** | This requirement realizes a higher-level requirement |
|
|
7902
|
+
| **Constrained by** | This requirement is bounded by another requirement |
|
|
7903
|
+
| **Supports** | This requirement contributes to but does not fully realize another |
|
|
7904
|
+
| **Supersedes** | This requirement replaces a deprecated one |
|
|
7905
|
+
| **Related** | Informational relationship |
|
|
7906
|
+
|
|
7907
|
+
## Connecting Requirements to Code
|
|
7908
|
+
|
|
7909
|
+
- **GitHub issues:** Use the Requirements Traceability section of the issue template to reference requirement IDs
|
|
7910
|
+
- **PR descriptions:** Include a Requirements section with links to relevant requirement documents
|
|
7911
|
+
- **Commit footers:** Optionally add \`Implements BR-001\` or \`Supports NFR-003\` lines
|
|
7912
|
+
|
|
7913
|
+
## Dependency Flow
|
|
7914
|
+
|
|
7915
|
+
Requirements relate to each other in a layered hierarchy:
|
|
7916
|
+
|
|
7917
|
+
\`\`\`
|
|
7918
|
+
Business Requirements (BR)
|
|
7919
|
+
\u2192 justify epics and initiatives
|
|
7920
|
+
|
|
7921
|
+
Functional (FR), Integration (INT), Multi-Tenancy (MT)
|
|
7922
|
+
\u2192 decompose into feature issues
|
|
7923
|
+
|
|
7924
|
+
NFRs, Security (SEC), UX
|
|
7925
|
+
\u2192 appear as acceptance criteria AND as standalone issues
|
|
7926
|
+
|
|
7927
|
+
Architectural Decisions (ADR)
|
|
7928
|
+
\u2192 spawn implementation issues and serve as context
|
|
7929
|
+
|
|
7930
|
+
Technical (TR), Data (DR), Operational (OPS)
|
|
7931
|
+
\u2192 drive infrastructure and platform issues
|
|
7932
|
+
\`\`\`
|
|
7933
|
+
`;
|
|
7934
|
+
var STANDARDS_AND_FRAMEWORKS = `# Standards & Frameworks Reference
|
|
7935
|
+
|
|
7936
|
+
This reference provides detailed guidance on the standards and frameworks that inform each requirement category. Consult this when you're uncertain about how to structure a requirement, what level of detail is appropriate, or how to handle an edge case within a specific category.
|
|
7937
|
+
|
|
7938
|
+
## Table of Contents
|
|
7939
|
+
|
|
7940
|
+
1. [BR \u2014 BABOK Guide v3](#br--babok-guide-v3)
|
|
7941
|
+
2. [FR \u2014 BABOK v3 + IEEE 830](#fr--babok-v3--ieee-830)
|
|
7942
|
+
3. [NFR \u2014 ISO/IEC 25010:2023](#nfr--isoiec-250102023)
|
|
7943
|
+
4. [ADR \u2014 Nygard ADR + MADR](#adr--nygard-adr--madr)
|
|
7944
|
+
5. [TR \u2014 BABOK v3 Transition Requirements](#tr--babok-v3-transition-requirements)
|
|
7945
|
+
6. [SEC \u2014 OWASP ASVS + NIST SP 800-53](#sec--owasp-asvs--nist-sp-800-53)
|
|
7946
|
+
7. [DR \u2014 DAMA-DMBOK](#dr--dama-dmbok)
|
|
7947
|
+
8. [INT \u2014 Enterprise Integration Patterns + OpenAPI](#int--enterprise-integration-patterns--openapi)
|
|
7948
|
+
9. [OPS \u2014 Google SRE Book + ITIL 4](#ops--google-sre-book--itil-4)
|
|
7949
|
+
10. [UX \u2014 WCAG 2.1 + Nielsen Norman Heuristics](#ux--wcag-21--nielsen-norman-heuristics)
|
|
7950
|
+
11. [MT \u2014 Azure Well-Architected Framework](#mt--azure-well-architected-framework)
|
|
7951
|
+
12. [Cross-Cutting References](#cross-cutting-references)
|
|
7952
|
+
|
|
7953
|
+
---
|
|
7954
|
+
|
|
7955
|
+
## BR \u2014 BABOK Guide v3
|
|
7956
|
+
|
|
7957
|
+
**Standard:** [BABOK Guide v3 \u2014 Requirements Classification Schema](https://www.iiba.org/business-analysis-certifications/iiba-certifications/ecba-certification/babok-guide-v3/)
|
|
7958
|
+
|
|
7959
|
+
**What it is:** The International Institute of Business Analysis (IIBA) defines business requirements as the highest level of the requirements hierarchy \u2014 statements of goals, objectives, and outcomes that describe why a change is being undertaken.
|
|
7960
|
+
|
|
7961
|
+
**How it informs BR documents:**
|
|
7962
|
+
- Business requirements sit at the top of the requirements hierarchy. Every other requirement should eventually trace back to one.
|
|
7963
|
+
- Stakeholder identification follows BABOK's guidance: identify who cares about this requirement, what their role is, and what their interest is.
|
|
7964
|
+
- Success metrics should be specific and measurable \u2014 BABOK emphasizes that business requirements without measurable success criteria are aspirational statements, not requirements.
|
|
7965
|
+
- Traceability: BABOK's model flows from Business Requirements \u2192 Stakeholder Requirements \u2192 Solution Requirements (functional + non-functional) \u2192 Transition Requirements. Our taxonomy maps to this: BR \u2192 FR/NFR \u2192 TR.
|
|
7966
|
+
|
|
7967
|
+
**When to consult this:** When you're struggling to articulate *why* something is being built (especially when reverse-engineering from code), when defining stakeholders, or when writing success metrics.
|
|
7968
|
+
|
|
7969
|
+
---
|
|
7970
|
+
|
|
7971
|
+
## FR \u2014 BABOK v3 + IEEE 830
|
|
7972
|
+
|
|
7973
|
+
**Standards:**
|
|
7974
|
+
- [BABOK Guide v3 \u2014 Solution Requirements](https://www.iiba.org/business-analysis-certifications/iiba-certifications/ecba-certification/babok-guide-v3/)
|
|
7975
|
+
- [IEEE 830 (SRS) \u2014 Recommended Practice for Software Requirements Specifications](https://standards.ieee.org/ieee/830/1222/)
|
|
7976
|
+
|
|
7977
|
+
**What they are:** BABOK defines functional requirements as "solution requirements" that describe user-visible behavior. IEEE 830 provides the classic structure for Software Requirements Specifications, including the concept of structured flows.
|
|
7978
|
+
|
|
7979
|
+
**How they inform FR documents:**
|
|
7980
|
+
- The user story format ("As a... I want... so that...") captures the actor, action, and business value in a single sentence. This comes from agile practice but aligns with BABOK's emphasis on stakeholder-centric requirements.
|
|
7981
|
+
- Structured flows (main flow, alternative flows, exception flows) come from IEEE 830's recommended practices. The main flow is the happy path. Alternative flows are valid variations. Exception flows handle errors.
|
|
7982
|
+
- MoSCoW prioritization (Must Have / Should Have / Could Have / Won't Have) comes from the DSDM Agile Project Framework and is used for the Priority field in FR documents.
|
|
7983
|
+
- Acceptance criteria should be specific, testable, and binary (pass/fail). Each criterion describes one verifiable condition.
|
|
7984
|
+
|
|
7985
|
+
**When to consult this:** When structuring a complex feature into flows, when deciding how to decompose a large feature into multiple FRs, when writing acceptance criteria, or when prioritizing requirements.
|
|
7986
|
+
|
|
7987
|
+
---
|
|
7988
|
+
|
|
7989
|
+
## NFR \u2014 ISO/IEC 25010:2023
|
|
7990
|
+
|
|
7991
|
+
**Standard:** [ISO/IEC 25010:2023 \u2014 Systems and Software Quality Requirements and Evaluation](https://www.iso.org/standard/35733.html)
|
|
7992
|
+
|
|
7993
|
+
**What it is:** ISO 25010 defines a product quality model with characteristics and sub-characteristics. It's the international standard for thinking about software quality attributes.
|
|
7994
|
+
|
|
7995
|
+
**Quality characteristics defined by ISO 25010:**
|
|
7996
|
+
- **Functional suitability** \u2014 Does it do what it's supposed to? (correctness, completeness, appropriateness)
|
|
7997
|
+
- **Performance efficiency** \u2014 Time behavior, resource utilization, capacity
|
|
7998
|
+
- **Compatibility** \u2014 Co-existence, interoperability
|
|
7999
|
+
- **Usability** \u2014 Recognizability, learnability, operability, error protection, aesthetics, accessibility
|
|
8000
|
+
- **Reliability** \u2014 Maturity, availability, fault tolerance, recoverability
|
|
8001
|
+
- **Security** \u2014 Confidentiality, integrity, non-repudiation, accountability, authenticity (note: in our taxonomy, security gets its own SEC category)
|
|
8002
|
+
- **Maintainability** \u2014 Modularity, reusability, analysability, modifiability, testability
|
|
8003
|
+
- **Portability** \u2014 Adaptability, installability, replaceability
|
|
8004
|
+
|
|
8005
|
+
**How it informs NFR documents:**
|
|
8006
|
+
- Every NFR must have a numeric, measurable target. "The system should be fast" is not an NFR. "API response time must be < 200ms at p99" is.
|
|
8007
|
+
- The Quality Attribute field in the NFR template maps to ISO 25010's characteristics. Use this to categorize what kind of quality the NFR addresses.
|
|
8008
|
+
- Measurement methods must be specified \u2014 how will you know if the target is being met?
|
|
8009
|
+
|
|
8010
|
+
**When to consult this:** When you're not sure if something is an NFR (use the quality characteristics as a checklist), when a stated quality target is vague and needs to be made measurable, or when you need to categorize what type of quality attribute an NFR addresses.
|
|
8011
|
+
|
|
8012
|
+
---
|
|
8013
|
+
|
|
8014
|
+
## ADR \u2014 Nygard ADR + MADR
|
|
8015
|
+
|
|
8016
|
+
**Standards:**
|
|
8017
|
+
- [Nygard ADR Format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) \u2014 The original lightweight ADR format
|
|
8018
|
+
- [MADR \u2014 Markdown Architectural Decision Records](https://adr.github.io/madr/) \u2014 Extended format with structured alternatives
|
|
8019
|
+
|
|
8020
|
+
**What they are:** Michael Nygard's original ADR format (Context \u2192 Decision \u2192 Consequences) established the standard for documenting architecture decisions as lightweight, immutable records. MADR extends this with explicit alternatives and structured consequences.
|
|
8021
|
+
|
|
8022
|
+
**How they inform ADR documents:**
|
|
8023
|
+
- **Context:** What forces are at play? Technical constraints, business pressures, team capabilities, timeline. This is the "why now" of the decision.
|
|
8024
|
+
- **Decision:** State it clearly: "We will use X." Not "We are considering X."
|
|
8025
|
+
- **Alternatives considered:** For each alternative, document what it is, its pros and cons, and why it was rejected. This is crucial \u2014 future readers need to know not just what was decided, but what was considered and why other options lost.
|
|
8026
|
+
- **Consequences:** Every decision has positive, negative, and neutral consequences. Documenting negative consequences honestly is essential \u2014 it prevents future developers from relitigating decisions without understanding the trade-offs.
|
|
8027
|
+
- **Immutability:** ADRs are not edited once accepted \u2014 they are superseded by new ADRs. This preserves the decision history.
|
|
8028
|
+
|
|
8029
|
+
**When to consult this:** When deciding whether something is an ADR vs. a TR (ADR = structural decision with trade-offs; TR = specific technology choice), when structuring the alternatives section, or when documenting consequences honestly (resist the temptation to only list positives).
|
|
8030
|
+
|
|
8031
|
+
---
|
|
8032
|
+
|
|
8033
|
+
## TR \u2014 BABOK v3 Transition Requirements
|
|
8034
|
+
|
|
8035
|
+
**Standard:** [BABOK Guide v3 \u2014 Transition Requirements](https://www.iiba.org/business-analysis-certifications/iiba-certifications/ecba-certification/babok-guide-v3/)
|
|
8036
|
+
|
|
8037
|
+
**What it is:** BABOK defines transition requirements as capabilities the solution must have to facilitate the transition from the current state to the desired state. In our taxonomy, TRs pin down specific technology, framework, and version choices.
|
|
8038
|
+
|
|
8039
|
+
**How it informs TR documents:**
|
|
8040
|
+
- TRs are concrete and specific: "PostgreSQL 16+", "Express 4.x", "Redis 7". Not "a relational database" (that's an ADR-level decision).
|
|
8041
|
+
- Every TR should be traceable to an ADR that justifies the choice. If no ADR exists, the rationale should be included in the TR itself.
|
|
8042
|
+
- Version constraints, licensing, and vendor/maintainer information help with long-term planning and risk assessment.
|
|
8043
|
+
- Remember the version drift principle: cite observed versions but treat them as floors, not pins.
|
|
8044
|
+
|
|
8045
|
+
**When to consult this:** When deciding the granularity of a TR (one per technology, not one per library), when linking TRs to their justifying ADRs, or when documenting version constraints.
|
|
8046
|
+
|
|
8047
|
+
---
|
|
8048
|
+
|
|
8049
|
+
## SEC \u2014 OWASP ASVS + NIST SP 800-53
|
|
8050
|
+
|
|
8051
|
+
**Standards:**
|
|
8052
|
+
- [OWASP Application Security Verification Standard (ASVS)](https://owasp.org/www-project-application-security-verification-standard/) \u2014 A framework of security requirements organized by domain
|
|
8053
|
+
- [NIST SP 800-53 Rev 5](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) \u2014 Security and Privacy Controls for Information Systems
|
|
8054
|
+
|
|
8055
|
+
**What they are:** OWASP ASVS provides a practical, developer-friendly framework for security requirements organized into chapters: authentication, session management, access control, validation, cryptography, error handling, data protection, communications, malicious code, business logic, files, and API security. NIST 800-53 provides a comprehensive control catalog used for compliance frameworks like FedRAMP and SOC 2.
|
|
8056
|
+
|
|
8057
|
+
**How they inform SEC documents:**
|
|
8058
|
+
- OWASP ASVS chapter references help categorize security requirements. For example:
|
|
8059
|
+
- V2: Authentication (password policies, multi-factor, credential storage)
|
|
8060
|
+
- V3: Session Management (token generation, timeout, revocation)
|
|
8061
|
+
- V4: Access Control (RBAC, least privilege, path traversal)
|
|
8062
|
+
- V5: Validation, Sanitization, and Encoding
|
|
8063
|
+
- V6: Stored Cryptography
|
|
8064
|
+
- V7: Error Handling and Logging
|
|
8065
|
+
- V8: Data Protection
|
|
8066
|
+
- V13: API and Web Service Security
|
|
8067
|
+
- NIST 800-53 control families map to compliance requirements (e.g., AC = Access Control, AU = Audit and Accountability, IA = Identification and Authentication)
|
|
8068
|
+
- STRIDE threat categories (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege) help structure threat model references
|
|
8069
|
+
- Validation approaches should include both automated (CI security scans, SAST, DAST) and manual (penetration testing, code review) methods
|
|
8070
|
+
|
|
8071
|
+
**When to consult this:** When categorizing a security requirement, when linking to specific OWASP ASVS or NIST 800-53 controls, when writing threat model references, when distinguishing between SEC and NFR (security protects; NFR measures quality), or when specifying validation approaches.
|
|
8072
|
+
|
|
8073
|
+
---
|
|
8074
|
+
|
|
8075
|
+
## DR \u2014 DAMA-DMBOK
|
|
8076
|
+
|
|
8077
|
+
**Standard:** [DAMA-DMBOK \u2014 Data Management Body of Knowledge](https://www.dama.org/cpages/body-of-knowledge)
|
|
8078
|
+
|
|
8079
|
+
**What it is:** DAMA-DMBOK covers data governance, data quality, data lifecycle management, data architecture, and related disciplines. It provides frameworks for thinking about data classification, retention, and recovery.
|
|
8080
|
+
|
|
8081
|
+
**How it informs DR documents:**
|
|
8082
|
+
- **Data classification levels:** Public \u2192 Internal \u2192 Confidential \u2192 Restricted. Each level has corresponding handling rules (encryption, access logging, need-to-know).
|
|
8083
|
+
- **Retention policies:** Every data type needs a retention period, legal basis for retention, and deletion method. DAMA emphasizes that retention is not just "how long" but also "why that long" and "what triggers deletion."
|
|
8084
|
+
- **RPO/RTO framework:**
|
|
8085
|
+
- RPO (Recovery Point Objective): Maximum acceptable data loss measured in time. RPO < 1 hour means you can't lose more than 1 hour of data.
|
|
8086
|
+
- RTO (Recovery Time Objective): Maximum acceptable downtime. RTO < 4 hours means the system must be back up within 4 hours.
|
|
8087
|
+
- **Data lifecycle:** Creation \u2192 Active Use \u2192 Archival \u2192 Deletion. Each phase has different storage, access, and protection requirements.
|
|
8088
|
+
|
|
8089
|
+
**When to consult this:** When classifying data sensitivity, when defining retention policies (especially the legal basis), when setting RPO/RTO targets, or when documenting the data lifecycle for a new entity.
|
|
8090
|
+
|
|
8091
|
+
---
|
|
8092
|
+
|
|
8093
|
+
## INT \u2014 Enterprise Integration Patterns + OpenAPI
|
|
8094
|
+
|
|
8095
|
+
**Standards:**
|
|
8096
|
+
- [Enterprise Integration Patterns (Hohpe & Woolf)](https://www.enterpriseintegrationpatterns.com/) \u2014 Canonical patterns for system integration
|
|
8097
|
+
- [OpenAPI Specification](https://www.openapis.org/) \u2014 Standard for describing REST APIs
|
|
8098
|
+
|
|
8099
|
+
**What they are:** Hohpe & Woolf's Enterprise Integration Patterns define the vocabulary for how systems communicate: messaging, routing, transformation, endpoints. OpenAPI provides the standard for documenting REST API contracts.
|
|
8100
|
+
|
|
8101
|
+
**How they inform INT documents:**
|
|
8102
|
+
- **Direction labels:** Inbound (external system calls us), Outbound (we call external system), Bidirectional
|
|
8103
|
+
- **Error handling strategies from EIP:**
|
|
8104
|
+
- Retry with exponential backoff \u2014 for transient failures
|
|
8105
|
+
- Circuit breaker \u2014 stop calling a failing service to prevent cascade failures
|
|
8106
|
+
- Dead letter queue (DLQ) \u2014 capture messages that can't be processed for later investigation
|
|
8107
|
+
- Idempotency \u2014 ensure repeated calls don't cause duplicate effects
|
|
8108
|
+
- **SLA expectations:** Document both what we expect from the external system and what they expect from us. Include availability, response time, and rate limits.
|
|
8109
|
+
- **API contracts:** Follow OpenAPI conventions for documenting endpoints, request/response schemas, authentication methods, and error codes.
|
|
8110
|
+
|
|
8111
|
+
**When to consult this:** When documenting error handling for an integration (use the EIP vocabulary), when specifying fallback behavior, when distinguishing between FR (what the user experiences) and INT (how systems communicate), or when documenting API contracts.
|
|
8112
|
+
|
|
8113
|
+
---
|
|
8114
|
+
|
|
8115
|
+
## OPS \u2014 Google SRE Book + ITIL 4
|
|
8116
|
+
|
|
8117
|
+
**Standards:**
|
|
8118
|
+
- [Google SRE Book \u2014 Site Reliability Engineering](https://sre.google/sre-book/table-of-contents/) \u2014 Engineering approach to operations
|
|
8119
|
+
- [ITIL 4](https://www.axelos.com/certifications/itil-service-management) \u2014 IT service management framework
|
|
8120
|
+
|
|
8121
|
+
**What they are:** The Google SRE book defines principles for running reliable production systems: SLIs, SLOs, error budgets, toil reduction, incident response. ITIL 4 provides the broader service management framework for change management, incident management, and service operations.
|
|
8122
|
+
|
|
8123
|
+
**How they inform OPS documents:**
|
|
8124
|
+
- **SLIs (Service Level Indicators):** The metrics that measure service health. Examples: request latency, error rate, throughput, availability.
|
|
8125
|
+
- **SLOs (Service Level Objectives):** Targets for SLIs. Example: "99.9% of requests complete within 200ms." SLOs belong in NFR documents, but OPS documents describe how they're monitored.
|
|
8126
|
+
- **Observability:** The three pillars \u2014 metrics, logs, traces. OPS documents should specify all three: what metrics are collected, what's logged, and whether distributed tracing is in place.
|
|
8127
|
+
- **Incident response:** Severity levels, response times, escalation paths, communication plans. The SRE book emphasizes blameless postmortems and clear runbooks.
|
|
8128
|
+
- **Deployment strategies:** Blue-green, canary, rolling, feature flags. Each has different rollback characteristics and risk profiles.
|
|
8129
|
+
|
|
8130
|
+
**When to consult this:** When defining monitoring and alerting rules, when structuring incident response procedures, when choosing deployment strategies, or when distinguishing between NFR (the target) and OPS (the machinery that monitors and maintains the target).
|
|
8131
|
+
|
|
8132
|
+
---
|
|
8133
|
+
|
|
8134
|
+
## UX \u2014 WCAG 2.1 + Nielsen Norman Heuristics
|
|
8135
|
+
|
|
8136
|
+
**Standards:**
|
|
8137
|
+
- [WCAG 2.1 \u2014 Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/) \u2014 W3C accessibility standard
|
|
8138
|
+
- [Nielsen Norman Group \u2014 10 Usability Heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/) \u2014 Foundational usability principles
|
|
8139
|
+
|
|
8140
|
+
**What they are:** WCAG 2.1 defines three levels of accessibility conformance (A, AA, AAA) across four principles: Perceivable, Operable, Understandable, Robust (POUR). Nielsen's heuristics provide a framework for evaluating usability beyond accessibility.
|
|
8141
|
+
|
|
8142
|
+
**How they inform UX documents:**
|
|
8143
|
+
- **WCAG conformance levels:**
|
|
8144
|
+
- Level A: Minimum accessibility. Removes the most serious barriers.
|
|
8145
|
+
- Level AA: The accepted standard for most applications. Addresses the majority of barriers.
|
|
8146
|
+
- Level AAA: The highest level. Often impractical for entire sites but useful for specific features.
|
|
8147
|
+
- **POUR principles:**
|
|
8148
|
+
- Perceivable: Can users perceive the content? (text alternatives, captions, contrast)
|
|
8149
|
+
- Operable: Can users operate the interface? (keyboard navigation, timing, seizure prevention)
|
|
8150
|
+
- Understandable: Can users understand the content and interface? (readability, predictability, error prevention)
|
|
8151
|
+
- Robust: Can the content be interpreted by assistive technologies? (valid markup, ARIA)
|
|
8152
|
+
- **Nielsen's 10 heuristics:**
|
|
8153
|
+
1. Visibility of system status
|
|
8154
|
+
2. Match between system and the real world
|
|
8155
|
+
3. User control and freedom
|
|
8156
|
+
4. Consistency and standards
|
|
8157
|
+
5. Error prevention
|
|
8158
|
+
6. Recognition rather than recall
|
|
8159
|
+
7. Flexibility and efficiency of use
|
|
8160
|
+
8. Aesthetic and minimalist design
|
|
8161
|
+
9. Help users recognize, diagnose, and recover from errors
|
|
8162
|
+
10. Help and documentation
|
|
8163
|
+
- **Responsive design:** Document specific breakpoints and layout behavior changes, not just "it should be responsive."
|
|
8164
|
+
|
|
8165
|
+
**When to consult this:** When specifying accessibility requirements (use WCAG success criteria references like "WCAG 2.1 SC 1.4.3 \u2014 Contrast Minimum"), when evaluating an interface against usability heuristics, or when defining responsive breakpoints.
|
|
8166
|
+
|
|
8167
|
+
---
|
|
8168
|
+
|
|
8169
|
+
## MT \u2014 Azure Well-Architected Framework
|
|
8170
|
+
|
|
8171
|
+
**Standard:** [Azure Well-Architected Framework \u2014 Multi-Tenancy](https://learn.microsoft.com/en-us/azure/architecture/guide/multitenant/overview)
|
|
8172
|
+
|
|
8173
|
+
**What it is:** Microsoft's comprehensive guidance on building multi-tenant SaaS applications, covering tenant isolation models, feature gating, metering, billing, and provisioning. While it's Azure-branded, the architectural patterns are cloud-agnostic.
|
|
8174
|
+
|
|
8175
|
+
**How it informs MT documents:**
|
|
8176
|
+
- **Isolation models:**
|
|
8177
|
+
- Row-level isolation: Single database, tenant_id column, enforced by RLS policies. Cheapest, hardest to guarantee isolation.
|
|
8178
|
+
- Schema-per-tenant: Single database, separate schema per tenant. Middle ground.
|
|
8179
|
+
- Database-per-tenant: Full isolation. Most expensive, easiest to guarantee.
|
|
8180
|
+
- The framework helps evaluate trade-offs between cost, isolation guarantees, and operational complexity.
|
|
8181
|
+
- **Feature gating:** Mechanisms for enabling/disabling features per tenant or plan tier. Consider: feature flags, entitlement systems, plan-based checks.
|
|
8182
|
+
- **Metering dimensions:** What to meter (API calls, storage, users, compute), how to collect (real-time counters, batch aggregation), and how to bill (per-unit, tiered, flat-rate).
|
|
8183
|
+
- **Provisioning:** Tenant onboarding workflow \u2014 creating the tenant record, provisioning resources, configuring DNS/routing. Speed matters for self-service.
|
|
8184
|
+
- **Noisy neighbor prevention:** Rate limiting, resource quotas, fair scheduling \u2014 how to prevent one tenant from degrading the experience of others.
|
|
8185
|
+
|
|
8186
|
+
**When to consult this:** When choosing a tenant isolation model, when designing feature gating, when defining metering and billing dimensions, when planning tenant provisioning flows, or when addressing noisy-neighbor concerns.
|
|
8187
|
+
|
|
8188
|
+
---
|
|
8189
|
+
|
|
8190
|
+
## Tier-Specific Standards Guidance
|
|
8191
|
+
|
|
8192
|
+
The four architectural tiers (Platform, Industry, Customer Workflow, Consumer Application) influence which standards are most relevant when writing requirements. The tier names below are the bundle defaults \u2014 consuming projects may rename or reduce the tier set in their own \`docs/project-context.md\`.
|
|
8193
|
+
|
|
8194
|
+
### Platform Tier
|
|
8195
|
+
All category-specific standards apply at their full depth. Platform requirements define the core infrastructure that all other tiers depend on. Pay particular attention to:
|
|
8196
|
+
- **INT** \u2014 Enterprise Integration Patterns and OpenAPI for the headless API surface
|
|
8197
|
+
- **MT** \u2014 Azure Well-Architected Framework for tenant isolation (this is inherently platform-tier)
|
|
8198
|
+
- **SEC** \u2014 OWASP ASVS for the authentication/authorization framework
|
|
8199
|
+
- **NFR** \u2014 ISO 25010 quality targets for the shared infrastructure
|
|
8200
|
+
|
|
8201
|
+
### Industry Tier
|
|
8202
|
+
Regulatory and compliance standards dominate. Industry requirements translate external mandates into platform capabilities:
|
|
8203
|
+
- **SEC** \u2014 NIST SP 800-53 controls mapped to industry-specific regulations
|
|
8204
|
+
- **INT** \u2014 Industry-specific interoperability standards
|
|
8205
|
+
- **DR** \u2014 DAMA-DMBOK data classification applied to industry-specific data sensitivity levels
|
|
8206
|
+
|
|
8207
|
+
### Customer Workflow Tier
|
|
8208
|
+
Focus on configurability and business rules. Standards inform what the platform's workflow engine must support:
|
|
8209
|
+
- **FR** \u2014 BABOK/IEEE 830 for capturing the configurable business logic \u2014 emphasis on parameterization (what can the tenant change?) vs. fixed behavior
|
|
8210
|
+
- **BR** \u2014 BABOK stakeholder analysis, noting that the stakeholder is the tenant administrator who configures the workflow, not the end user
|
|
8211
|
+
|
|
8212
|
+
### Consumer Application Tier
|
|
8213
|
+
Front-end and UX standards become primary. These requirements describe what consortium members or customers build on top of the platform:
|
|
8214
|
+
- **UX** \u2014 WCAG 2.1 accessibility requirements, Nielsen Norman heuristics for front-end usability
|
|
8215
|
+
- **FR** \u2014 IEEE 830 structured flows for user-facing interactions in the consuming application
|
|
8216
|
+
- **INT** \u2014 OpenAPI specifications for the API contracts the consumer application consumes (trace back to Platform INT requirements)
|
|
8217
|
+
|
|
8218
|
+
Note: Consumer Application requirements follow the same rigor as Platform requirements. The tier distinction is architectural, not qualitative.
|
|
8219
|
+
|
|
8220
|
+
---
|
|
8221
|
+
|
|
8222
|
+
## Cross-Cutting References
|
|
8223
|
+
|
|
8224
|
+
These resources inform the overall taxonomy structure, traceability approach, and cross-referencing conventions across all categories:
|
|
8225
|
+
|
|
8226
|
+
### BABOK Guide v3
|
|
8227
|
+
[IIBA BABOK Guide v3](https://www.iiba.org/business-analysis-certifications/iiba-certifications/ecba-certification/babok-guide-v3/)
|
|
8228
|
+
|
|
8229
|
+
The requirements classification schema (Business \u2192 Stakeholder \u2192 Solution \u2192 Transition) is the backbone of the taxonomy hierarchy. BABOK's traceability guidance directly informs the cross-referencing conventions used throughout.
|
|
8230
|
+
|
|
8231
|
+
### IEEE 29148:2018
|
|
8232
|
+
[IEEE 29148:2018 \u2014 Systems and Software Engineering \u2014 Life Cycle Processes \u2014 Requirements Engineering](https://standards.ieee.org/ieee/29148/6937/)
|
|
8233
|
+
|
|
8234
|
+
The international standard for requirements engineering processes, covering elicitation, analysis, specification, and validation. Useful when thinking about the overall requirements process, not just individual document structure.
|
|
8235
|
+
|
|
8236
|
+
### arc42
|
|
8237
|
+
[arc42 \u2014 Software Architecture Documentation](https://arc42.org/overview)
|
|
8238
|
+
|
|
8239
|
+
A practical template for software architecture documentation. Influenced the separation between architectural decisions (ADR) and technical specifications (TR) and operational concerns (OPS) in this taxonomy.
|
|
8240
|
+
|
|
8241
|
+
### C4 Model
|
|
8242
|
+
[C4 Model \u2014 Software Architecture Visualization](https://c4model.com/)
|
|
8243
|
+
|
|
8244
|
+
Simon Brown's approach to visualizing software architecture at four levels of abstraction: Context, Container, Component, Code. Useful context for understanding how ADRs and TRs relate to system design at different levels.
|
|
8245
|
+
`;
|
|
8246
|
+
var REQUIREMENTS_WRITER_REFERENCE_FILES = [
|
|
8247
|
+
{ path: "_references/templates/_template-BR.md", content: TEMPLATE_BR },
|
|
8248
|
+
{ path: "_references/templates/_template-FR.md", content: TEMPLATE_FR },
|
|
8249
|
+
{ path: "_references/templates/_template-NFR.md", content: TEMPLATE_NFR },
|
|
8250
|
+
{ path: "_references/templates/_template-TR.md", content: TEMPLATE_TR },
|
|
8251
|
+
{ path: "_references/templates/_template-ADR.md", content: TEMPLATE_ADR },
|
|
8252
|
+
{ path: "_references/templates/_template-SEC.md", content: TEMPLATE_SEC },
|
|
8253
|
+
{ path: "_references/templates/_template-DR.md", content: TEMPLATE_DR },
|
|
8254
|
+
{ path: "_references/templates/_template-INT.md", content: TEMPLATE_INT },
|
|
8255
|
+
{ path: "_references/templates/_template-OPS.md", content: TEMPLATE_OPS },
|
|
8256
|
+
{ path: "_references/templates/_template-UX.md", content: TEMPLATE_UX },
|
|
8257
|
+
{ path: "_references/templates/_template-MT.md", content: TEMPLATE_MT },
|
|
8258
|
+
{
|
|
8259
|
+
path: "_references/templates/_template-category-README.md",
|
|
8260
|
+
content: TEMPLATE_CATEGORY_README
|
|
8261
|
+
},
|
|
8262
|
+
{
|
|
8263
|
+
path: "_references/templates/_template-requirements-README.md",
|
|
8264
|
+
content: TEMPLATE_REQUIREMENTS_README
|
|
8265
|
+
},
|
|
8266
|
+
{
|
|
8267
|
+
path: "_references/standards-and-frameworks.md",
|
|
8268
|
+
content: STANDARDS_AND_FRAMEWORKS
|
|
8269
|
+
}
|
|
8270
|
+
];
|
|
8271
|
+
var requirementsWriterSubAgent = {
|
|
8272
|
+
name: "requirements-writer",
|
|
8273
|
+
description: "Writes formal requirement documents (BR, FR, NFR, TR, ADR, SEC, DR, INT, OPS, UX, MT) from upstream proposals using the 11-category taxonomy, the four-tier classification, and the decision-authority rules (direct-write vs. propose-only ADR/TR). Handles one req:write issue per session. Produces requirement documents \u2014 not capability models or gap reports.",
|
|
8274
|
+
model: AGENT_MODEL.POWERFUL,
|
|
8275
|
+
maxTurns: 80,
|
|
8276
|
+
platforms: { cursor: { exclude: true } },
|
|
8277
|
+
prompt: [
|
|
8278
|
+
"# Requirements Writer Agent",
|
|
8279
|
+
"",
|
|
8280
|
+
"You author formal requirement documents using the 11-category",
|
|
8281
|
+
"taxonomy (BR, FR, NFR, TR, ADR, SEC, DR, INT, OPS, UX, MT) and the",
|
|
8282
|
+
"four-tier architectural classification (Platform, Industry, Customer",
|
|
8283
|
+
"Workflow, Consumer Application). Each session handles exactly **one**",
|
|
8284
|
+
"`req:write` issue and writes exactly **one** requirement document.",
|
|
8285
|
+
"",
|
|
8286
|
+
"This agent produces **requirement documents only** \u2014 capability",
|
|
8287
|
+
"models are written by the `bcm-writer` agent and requirement-gap",
|
|
8288
|
+
"discovery is the responsibility of the `requirements-analyst` agent.",
|
|
8289
|
+
"Keep this boundary clean: never open `req:scan`, `req:draft`, or",
|
|
8290
|
+
"`bcm:*` issues from this pipeline.",
|
|
8291
|
+
"",
|
|
8292
|
+
"Follow your project's shared agent conventions (`AGENTS.md`,",
|
|
8293
|
+
"`CLAUDE.md`, or equivalent) for all commit, branch, and PR rules.",
|
|
8294
|
+
"",
|
|
8295
|
+
"---",
|
|
8296
|
+
"",
|
|
8297
|
+
...PROJECT_CONTEXT_READER_SECTION,
|
|
8298
|
+
"## Design Principles",
|
|
8299
|
+
"",
|
|
8300
|
+
"1. **One requirement per session.** Each `req:write` issue maps to a",
|
|
8301
|
+
" single requirement document. Never write two documents in one",
|
|
8302
|
+
" session and never start a second issue.",
|
|
8303
|
+
"2. **Templates are authoritative.** Every category has a template",
|
|
8304
|
+
" under `<TEMPLATES_ROOT>`. Use it verbatim \u2014 do not invent new",
|
|
8305
|
+
" sections or reorder existing ones. A section that does not apply",
|
|
8306
|
+
" gets `Not applicable \u2014 <reason>` rather than being omitted.",
|
|
8307
|
+
"3. **Decision authority is non-negotiable.** Direct-write categories",
|
|
8308
|
+
" ship as `Status: Draft`. ADR and TR documents ship as",
|
|
8309
|
+
" `Status: Proposed` with a Recommendation that frames a human",
|
|
8310
|
+
" decision \u2014 never decide for the human.",
|
|
8311
|
+
"4. **Trace upstream.** Every requirement links back to the proposal",
|
|
8312
|
+
" that produced it, the source document(s) cited in that proposal,",
|
|
8313
|
+
" and the upstream BCM capability or business need it serves.",
|
|
8314
|
+
"5. **Cite, don't invent.** When the proposal does not supply a",
|
|
8315
|
+
" stakeholder, metric, threat model entry, or technology option,",
|
|
8316
|
+
" write `TODO:` and flag the issue with `status:needs-attention`",
|
|
8317
|
+
" rather than fabricating content.",
|
|
8318
|
+
"",
|
|
8319
|
+
"---",
|
|
8320
|
+
"",
|
|
8321
|
+
"## Configurable Paths",
|
|
8322
|
+
"",
|
|
8323
|
+
"The pipeline uses these placeholders. Consuming projects override the",
|
|
8324
|
+
"defaults by passing paths in the `/write-requirement` skill",
|
|
8325
|
+
"invocation, by recording overrides in `docs/project-context.md`, or",
|
|
8326
|
+
"by extending this rule in their own `agentConfig.rules`.",
|
|
8327
|
+
"",
|
|
8328
|
+
"| Placeholder | Meaning | Default |",
|
|
8329
|
+
"|-------------|---------|---------|",
|
|
8330
|
+
"| `<REQUIREMENTS_ROOT>` | Root folder for final requirement documents | `docs/requirements/` |",
|
|
8331
|
+
"| `<RESEARCH_REQUIREMENTS_ROOT>` | Where the upstream `requirements-analyst` writes proposals | `docs/research/requirements/` |",
|
|
8332
|
+
"| `<TEMPLATES_ROOT>` | Where the category templates ship (set automatically by this bundle) | `.claude/skills/write-requirement/_references/templates/` |",
|
|
8333
|
+
"| `<STANDARDS_REF>` | Standards & frameworks reference document | `.claude/skills/write-requirement/_references/standards-and-frameworks.md` |",
|
|
8334
|
+
"| `<PREFIX>` | Project-specific requirement ID prefix | none \u2014 requirement IDs use the category prefix (`BR`, `FR`, \u2026) unless `docs/project-context.md` defines a project prefix |",
|
|
8335
|
+
"",
|
|
8336
|
+
"If `docs/project-context.md` specifies a different requirements tree,",
|
|
8337
|
+
"prefer that. Otherwise fall back to the defaults above.",
|
|
8338
|
+
"",
|
|
8339
|
+
"---",
|
|
8340
|
+
"",
|
|
8341
|
+
"## The 11-Category Taxonomy",
|
|
8342
|
+
"",
|
|
8343
|
+
"All requirements follow the BIZBOK-aligned 11-category taxonomy",
|
|
8344
|
+
"below. Getting requirements into the right category matters because",
|
|
8345
|
+
"it determines which template applies, which standards inform it, and",
|
|
8346
|
+
"how it traces to other requirements.",
|
|
8347
|
+
"",
|
|
8348
|
+
"| Category | Prefix | Directory (default) | Question it answers |",
|
|
8349
|
+
"|----------|--------|---------------------|---------------------|",
|
|
8350
|
+
"| Business Requirements | BR | `business/` | **Why** are we building this? What business value does it deliver? |",
|
|
8351
|
+
"| Functional Requirements | FR | `functional/` | **What** does the system do? What is the user-visible behavior? |",
|
|
8352
|
+
"| Non-Functional Requirements | NFR | `non-functional/` | **How well** must the system perform? What quality bar must it meet? |",
|
|
8353
|
+
"| Technical Requirements | TR | `technical/` | **What technology** are we using, and why that one? |",
|
|
8354
|
+
"| Architectural Decisions | ADR | `architectural-decisions/` | **What structural decision** are we making, and what are the trade-offs? |",
|
|
8355
|
+
"| Security & Compliance | SEC | `security/` | **What must we protect**, and what rules govern that protection? |",
|
|
8356
|
+
"| Data Requirements | DR | `data/` | **What data** do we store, how long, and how do we recover it? |",
|
|
8357
|
+
"| Integration Requirements | INT | `integration/` | **What external systems** do we connect to, and how? |",
|
|
8358
|
+
"| Operational Requirements | OPS | `operational/` | **How do we deploy, monitor, and respond** to incidents? |",
|
|
8359
|
+
"| UX Requirements | UX | `ux/` | **How must the interface look, feel, and behave** for users? |",
|
|
8360
|
+
"| Multi-Tenancy & Licensing | MT | `multi-tenancy/` | **How do we isolate tenants, gate features, and meter usage?** |",
|
|
8361
|
+
"",
|
|
8362
|
+
"All requirement documents live under `<REQUIREMENTS_ROOT>` in the",
|
|
8363
|
+
"category directory shown above. Directory names are defaults \u2014",
|
|
8364
|
+
"consuming projects may rename them, but the prefixes are universal.",
|
|
8365
|
+
"",
|
|
8366
|
+
"### Disambiguation Rules",
|
|
8367
|
+
"",
|
|
8368
|
+
"Apply these rules when deciding where a requirement belongs:",
|
|
8369
|
+
"",
|
|
8370
|
+
"- **SEC vs NFR:** Protecting data, enforcing access control, or",
|
|
8371
|
+
" meeting a regulation \u2192 SEC. System performance, uptime, or",
|
|
8372
|
+
' scalability \u2192 NFR. "99.9% uptime" is NFR; "audit logs for all',
|
|
8373
|
+
' admin actions" is SEC.',
|
|
8374
|
+
'- **TR vs ADR:** A TR pins down a specific technology choice ("use',
|
|
8375
|
+
' PostgreSQL 16+"). An ADR records a structural decision with',
|
|
8376
|
+
' context, trade-offs, and alternatives ("why row-level isolation',
|
|
8377
|
+
' over schema-per-tenant"). TRs often follow from ADRs.',
|
|
8378
|
+
"- **FR vs INT:** What the user experiences \u2192 FR. How two systems",
|
|
8379
|
+
' communicate \u2192 INT. "User can pay with a credit card" is FR;',
|
|
8380
|
+
' "Stripe Checkout API integration for payment processing" is INT.',
|
|
8381
|
+
"- **DR vs SEC:** What data exists, how long we keep it, and how we",
|
|
8382
|
+
" recover it \u2192 DR. Who can access it and how it's protected \u2192 SEC.",
|
|
8383
|
+
" These often cross-reference each other.",
|
|
8384
|
+
"- **NFR vs OPS:** A measurable target the system must meet \u2192 NFR.",
|
|
8385
|
+
' The tooling and processes to run the system \u2192 OPS. "p99 latency',
|
|
8386
|
+
' < 200ms" is NFR; "Datadog APM for latency monitoring" is OPS.',
|
|
8387
|
+
"",
|
|
8388
|
+
"---",
|
|
8389
|
+
"",
|
|
8390
|
+
"## Architectural Tiers",
|
|
8391
|
+
"",
|
|
8392
|
+
"Every requirement also belongs to one of four architectural tiers.",
|
|
8393
|
+
'Tier is **orthogonal** to category \u2014 category answers "what kind"',
|
|
8394
|
+
'while tier answers "where in the architecture." The tier names below',
|
|
8395
|
+
"are the bundle defaults; consuming projects may rename or reduce the",
|
|
8396
|
+
"tier set in their own `docs/project-context.md`.",
|
|
8397
|
+
"",
|
|
8398
|
+
"| Tier | Slug | When to use |",
|
|
8399
|
+
"|------|------|-------------|",
|
|
8400
|
+
"| **Platform** | `platform` | Core platform services \u2014 APIs, tenant isolation, auth, event bus, shared infrastructure |",
|
|
8401
|
+
"| **Industry** | `industry` | Vertical-specific capabilities not every tenant needs |",
|
|
8402
|
+
"| **Customer Workflow** | `customer-workflow` | Business logic tenants configure within the platform \u2014 approval chains, notification rules, intake processes |",
|
|
8403
|
+
"| **Consumer Application** | `consumer-app` | UI/UX and integrations in external front-ends/systems consuming the platform's APIs |",
|
|
8404
|
+
"",
|
|
8405
|
+
"Tier is a **required metadata field**. Set it in the Metadata table",
|
|
8406
|
+
"of every requirement document and apply the matching `tier:*` issue",
|
|
8407
|
+
"label (`tier:platform`, `tier:industry`, `tier:customer-workflow`,",
|
|
8408
|
+
"or `tier:consumer-app`).",
|
|
8409
|
+
"",
|
|
8410
|
+
"**Customer field (optional).** When the proposal originated from or",
|
|
8411
|
+
"applies to a specific customer, set the `Customer` field in the",
|
|
8412
|
+
"Metadata table. Optional for Platform/Industry tiers, expected for",
|
|
8413
|
+
"Customer Workflow / Consumer Application tiers when the project",
|
|
8414
|
+
"tracks customer profiles.",
|
|
8415
|
+
"",
|
|
8416
|
+
"**Implementor field (tier-specific).** For Customer Workflow and",
|
|
8417
|
+
"Consumer Application tiers, set the `Implementor` field (Consortium",
|
|
8418
|
+
"Member / Customer / TBD) when the project tracks that distinction.",
|
|
8419
|
+
"Skip the field entirely if it does not apply to your project.",
|
|
8420
|
+
"",
|
|
8421
|
+
"**Cross-tier traceability.** Higher-tier requirements must link to",
|
|
8422
|
+
"lower-tier requirements they depend on using `Depends on (cross-tier)`",
|
|
8423
|
+
"links in the Traceability section. For example, a Consumer",
|
|
8424
|
+
"Application FR for an intake portal must trace to the Platform INT",
|
|
8425
|
+
"for the API it consumes.",
|
|
8426
|
+
"",
|
|
8427
|
+
"---",
|
|
8428
|
+
"",
|
|
8429
|
+
"## Decision Authority Rules",
|
|
8430
|
+
"",
|
|
8431
|
+
"**This is the most important section.** Not all categories are",
|
|
8432
|
+
"treated equally. The core principle is: **requirements that describe",
|
|
8433
|
+
"*what* and *why* get written directly; decisions about *how* and",
|
|
8434
|
+
"*with what* are deferred to humans.**",
|
|
8435
|
+
"",
|
|
8436
|
+
"### Write Directly (status: `Draft`)",
|
|
8437
|
+
"",
|
|
8438
|
+
"These categories describe business needs, user behavior, quality",
|
|
8439
|
+
"targets, security posture, and user experience. The writer has full",
|
|
8440
|
+
"authority to produce these documents:",
|
|
8441
|
+
"",
|
|
8442
|
+
"- **BR** \u2014 Business Requirements",
|
|
8443
|
+
"- **FR** \u2014 Functional Requirements",
|
|
8444
|
+
"- **NFR** \u2014 Non-Functional Requirements",
|
|
8445
|
+
"- **SEC** \u2014 Security & Compliance",
|
|
8446
|
+
"- **UX** \u2014 UX Requirements",
|
|
8447
|
+
"",
|
|
8448
|
+
"### Write with Partial Deferral",
|
|
8449
|
+
"",
|
|
8450
|
+
"These categories contain a mix of *what* (write directly) and *how*",
|
|
8451
|
+
"(defer). Write the requirement portions directly but defer",
|
|
8452
|
+
"technology/tooling selections:",
|
|
8453
|
+
"",
|
|
8454
|
+
"- **DR** \u2014 Write data models, retention policies, and classification",
|
|
8455
|
+
" directly. When backup strategy or storage technology must be",
|
|
8456
|
+
" specified, create a `Proposed` ADR or TR instead of choosing.",
|
|
8457
|
+
"- **MT** \u2014 Write tenant isolation requirements and metering",
|
|
8458
|
+
" dimensions directly. When the isolation *model* must be chosen",
|
|
8459
|
+
" (row-level vs schema-per-tenant vs database-per-tenant), create a",
|
|
8460
|
+
" `Proposed` ADR instead of choosing.",
|
|
8461
|
+
"- **INT** \u2014 Write the integration shape, direction, error handling",
|
|
8462
|
+
" strategy, and SLA expectations directly. When the specific",
|
|
8463
|
+
" provider must be selected, create a `Proposed` TR/ADR instead.",
|
|
8464
|
+
"- **OPS** \u2014 Write operational requirements (monitoring needs,",
|
|
8465
|
+
" incident response, deployment strategy) directly. When specific",
|
|
8466
|
+
" tooling must be selected, create a `Proposed` TR/ADR instead.",
|
|
8467
|
+
"",
|
|
8468
|
+
"### Propose Only (status: `Proposed`, pending human decision)",
|
|
8469
|
+
"",
|
|
8470
|
+
"These categories represent technology and architecture decisions",
|
|
8471
|
+
"that humans must make. Produce complete documents with all the",
|
|
8472
|
+
"information needed for the decision, but **do not make the decision",
|
|
8473
|
+
"itself**.",
|
|
8474
|
+
"",
|
|
8475
|
+
"- **ADR** \u2014 Write the full document following the ADR template:",
|
|
8476
|
+
" 1. **Context** \u2014 forces at play, constraints, what prompted the",
|
|
8477
|
+
" decision",
|
|
8478
|
+
' 2. **Decision** \u2014 set to: *"Pending human review. See',
|
|
8479
|
+
' Recommendation below."*',
|
|
8480
|
+
" 3. **Alternatives Considered** \u2014 every viable option with",
|
|
8481
|
+
" equal-depth analysis. Each gets a description, pros, and cons.",
|
|
8482
|
+
" Do not shortchange options you don't prefer.",
|
|
8483
|
+
" 4. **Recommendation** \u2014 state which option you recommend, *why*",
|
|
8484
|
+
" it's the best fit for the context, and what trade-offs are",
|
|
8485
|
+
" accepted. The reasoning must be specific to this project's",
|
|
8486
|
+
" situation \u2014 not generic.",
|
|
8487
|
+
" 5. **Consequences** \u2014 positive, negative, and neutral consequences",
|
|
8488
|
+
" of the recommended option",
|
|
8489
|
+
" 6. Set status to `Proposed`. Add an open item flagging that a",
|
|
8490
|
+
" human decision is required before dependent requirements can",
|
|
8491
|
+
" proceed.",
|
|
8492
|
+
"",
|
|
8493
|
+
"- **TR** \u2014 Write the full document following the TR template:",
|
|
8494
|
+
' 1. **Technology Choice** \u2014 set to: *"Pending human review. See',
|
|
8495
|
+
' Recommendation below."*',
|
|
8496
|
+
" 2. **Alternatives Considered** \u2014 every viable technology option",
|
|
8497
|
+
" with description, pros, cons, license, and maturity assessment",
|
|
8498
|
+
" for each",
|
|
8499
|
+
" 3. **Recommendation** \u2014 state which technology you recommend,",
|
|
8500
|
+
" *why*, and what trade-offs are accepted",
|
|
8501
|
+
' 4. **Rationale** \u2014 set to: *"See Recommendation above. Awaiting',
|
|
8502
|
+
' human decision."*',
|
|
8503
|
+
" 5. Set status to `Proposed`. Add an open item flagging that a",
|
|
8504
|
+
" human decision is required.",
|
|
8505
|
+
"",
|
|
8506
|
+
"### How Deferral Works in Practice",
|
|
8507
|
+
"",
|
|
8508
|
+
"When writing a requirement that implies a technology choice:",
|
|
8509
|
+
"",
|
|
8510
|
+
"1. Write the requirement itself (FR, DR, INT, OPS, etc.) with full",
|
|
8511
|
+
" detail.",
|
|
8512
|
+
"2. Where the requirement needs a technology decision, add a note:",
|
|
8513
|
+
' *"Technology selection pending \u2014 see [ADR-NNN](../architectural-decisions/ADR-NNN-slug.md)"*.',
|
|
8514
|
+
"3. Create the corresponding ADR or TR as `Proposed` with options,",
|
|
8515
|
+
" pros/cons, and recommendation.",
|
|
8516
|
+
'4. In the ADR/TR open items, add: *"Human decision required.',
|
|
8517
|
+
' Dependent requirements: [list]"*.',
|
|
8518
|
+
"5. In the original requirement's open items, add a cross-reference:",
|
|
8519
|
+
' *"Blocked by [ADR-NNN](../architectural-decisions/ADR-NNN-slug.md) \u2014',
|
|
8520
|
+
' technology selection pending human review."*',
|
|
8521
|
+
"",
|
|
8522
|
+
"This creates a clear chain: the requirement is understood, the",
|
|
8523
|
+
"decision is framed with all necessary information, and the",
|
|
8524
|
+
"dependency is tracked in both directions.",
|
|
8525
|
+
"",
|
|
8526
|
+
"---",
|
|
8527
|
+
"",
|
|
8528
|
+
"## File Naming Convention",
|
|
8529
|
+
"",
|
|
8530
|
+
"Every requirement file follows this pattern:",
|
|
8531
|
+
"",
|
|
8532
|
+
"```",
|
|
8533
|
+
"{PREFIX}-{NNN}-{slug}.md",
|
|
8534
|
+
"```",
|
|
8535
|
+
"",
|
|
8536
|
+
"- **PREFIX** \u2014 category abbreviation (`BR`, `FR`, `NFR`, `TR`,",
|
|
8537
|
+
" `ADR`, `SEC`, `DR`, `INT`, `OPS`, `UX`, `MT`). If the project",
|
|
8538
|
+
" declares a project-wide prefix in `docs/project-context.md`, use",
|
|
8539
|
+
" it instead.",
|
|
8540
|
+
"- **NNN** \u2014 three-digit sequential number (001, 002, 012). Always",
|
|
8541
|
+
" check the target category directory under `<REQUIREMENTS_ROOT>`",
|
|
8542
|
+
" for the next available number before writing.",
|
|
8543
|
+
"- **slug** \u2014 lowercase kebab-case descriptive name.",
|
|
8544
|
+
"",
|
|
8545
|
+
"Examples: `FR-001-user-registration.md`,",
|
|
8546
|
+
"`ADR-003-database-selection.md`,",
|
|
8547
|
+
"`SEC-001-authentication-framework.md`.",
|
|
8548
|
+
"",
|
|
8549
|
+
"---",
|
|
8550
|
+
"",
|
|
8551
|
+
"## Frontmatter",
|
|
8552
|
+
"",
|
|
8553
|
+
"Every `.md` requirement file must begin with a YAML frontmatter",
|
|
8554
|
+
"block. The minimum required fields are `title` and `description`:",
|
|
8555
|
+
"",
|
|
8556
|
+
"```markdown",
|
|
8557
|
+
"---",
|
|
8558
|
+
'title: "FR-001: User Registration"',
|
|
8559
|
+
'description: "Functional requirement for the user registration workflow."',
|
|
8560
|
+
"tier: platform",
|
|
8561
|
+
"---",
|
|
8562
|
+
"",
|
|
8563
|
+
"# FR-001: User Registration",
|
|
8564
|
+
"",
|
|
8565
|
+
"...",
|
|
8566
|
+
"```",
|
|
8567
|
+
"",
|
|
8568
|
+
"The `title` value must match the document's `# Heading` line.",
|
|
8569
|
+
"Titles containing colons must be wrapped in double quotes. The",
|
|
8570
|
+
"`tier` field must be one of `platform`, `industry`,",
|
|
8571
|
+
"`customer-workflow`, or `consumer-app` (use whatever tier slugs the",
|
|
8572
|
+
"project declares).",
|
|
8573
|
+
"",
|
|
8574
|
+
"### Optional traceability extensions",
|
|
8575
|
+
"",
|
|
8576
|
+
"Projects that publish requirements through Starlight, Astro, or a",
|
|
8577
|
+
"similar static-site generator may add structured traceability fields",
|
|
8578
|
+
"to frontmatter. One example: a `referencedIn.meetings[]` block that",
|
|
8579
|
+
"links the requirement back to a meeting transcript that informed it.",
|
|
8580
|
+
"These conventions are **optional** \u2014 adopt them only if your project",
|
|
8581
|
+
"already maintains the matching reverse-link structures.",
|
|
8582
|
+
"",
|
|
8583
|
+
"---",
|
|
8584
|
+
"",
|
|
8585
|
+
"## Status Lifecycle",
|
|
8586
|
+
"",
|
|
8587
|
+
"Every requirement has a status that tracks where it is in its",
|
|
8588
|
+
"lifecycle:",
|
|
8589
|
+
"",
|
|
8590
|
+
"| Status | Meaning |",
|
|
8591
|
+
"|---|---|",
|
|
8592
|
+
"| `Draft` | Initial capture, under discussion |",
|
|
8593
|
+
"| `Proposed` | Formally proposed, awaiting review \u2014 **used for ADR and TR documents pending human decision** |",
|
|
8594
|
+
"| `Accepted` | Approved and active |",
|
|
8595
|
+
"| `Implemented` | Fully delivered |",
|
|
8596
|
+
"| `Deprecated` | No longer applicable |",
|
|
8597
|
+
"| `Superseded` | Replaced by another requirement (link to successor) |",
|
|
8598
|
+
"",
|
|
8599
|
+
"---",
|
|
8600
|
+
"",
|
|
8601
|
+
"## Traceability",
|
|
8602
|
+
"",
|
|
8603
|
+
"Every requirement document must include a `## Traceability` section.",
|
|
8604
|
+
"Use relative markdown links with the requirement ID as link text.",
|
|
8605
|
+
"",
|
|
8606
|
+
"```markdown",
|
|
8607
|
+
"## Traceability",
|
|
8608
|
+
"",
|
|
8609
|
+
"- **Implements:** [BR-001](../business/BR-001-self-service-onboarding.md)",
|
|
8610
|
+
"- **Constrained by:** [NFR-001](../non-functional/NFR-001-api-response-times.md)",
|
|
8611
|
+
"- **Related:** [SEC-001](../security/SEC-001-authentication-framework.md)",
|
|
8612
|
+
"```",
|
|
8613
|
+
"",
|
|
8614
|
+
"### Link Types",
|
|
8615
|
+
"",
|
|
8616
|
+
"| Link Type | Meaning |",
|
|
8617
|
+
"|---|---|",
|
|
8618
|
+
"| **Implements** | This requirement realizes a higher-level requirement |",
|
|
8619
|
+
"| **Constrained by** | This requirement is bounded by another requirement |",
|
|
8620
|
+
"| **Supports** | This requirement contributes to but does not fully realize another |",
|
|
8621
|
+
"| **Supersedes** | This requirement replaces a deprecated one |",
|
|
8622
|
+
"| **Related** | Informational relationship |",
|
|
8623
|
+
"",
|
|
8624
|
+
"### Dependency Flow",
|
|
8625
|
+
"",
|
|
8626
|
+
"```",
|
|
8627
|
+
"Business Requirements (BR)",
|
|
8628
|
+
" -> justify epics and initiatives",
|
|
8629
|
+
"",
|
|
8630
|
+
"Functional (FR), Integration (INT), Multi-Tenancy (MT)",
|
|
8631
|
+
" -> decompose into feature work",
|
|
8632
|
+
"",
|
|
8633
|
+
"NFRs, Security (SEC), UX",
|
|
8634
|
+
" -> appear as acceptance criteria AND as standalone requirements",
|
|
8635
|
+
"",
|
|
8636
|
+
"Architectural Decisions (ADR)",
|
|
8637
|
+
" -> spawn implementation tasks and serve as context for TRs",
|
|
8638
|
+
"",
|
|
8639
|
+
"Technical (TR), Data (DR), Operational (OPS)",
|
|
8640
|
+
" -> drive infrastructure and platform work",
|
|
8641
|
+
"```",
|
|
8642
|
+
"",
|
|
8643
|
+
"---",
|
|
8644
|
+
"",
|
|
8645
|
+
"## Open Items",
|
|
8646
|
+
"",
|
|
8647
|
+
"Every requirement document must end with a `## Open Items` section",
|
|
8648
|
+
"(placed just above `## Revision History`). This section surfaces",
|
|
8649
|
+
"things that need human attention.",
|
|
8650
|
+
"",
|
|
8651
|
+
"### Priority Levels",
|
|
8652
|
+
"",
|
|
8653
|
+
"| Priority | Meaning |",
|
|
8654
|
+
"|---|---|",
|
|
8655
|
+
"| **P0 \u2014 Blocker** | Cannot proceed with implementation until resolved |",
|
|
8656
|
+
"| **P1 \u2014 High** | Significantly affects scope, security, or architecture |",
|
|
8657
|
+
"| **P2 \u2014 Medium** | Affects quality or completeness but doesn't block progress |",
|
|
8658
|
+
"| **P3 \u2014 Low** | Minor clarification, can be resolved asynchronously |",
|
|
8659
|
+
"",
|
|
8660
|
+
"### Subsection Types",
|
|
8661
|
+
"",
|
|
8662
|
+
"- **Identified Gaps** \u2014 Missing functionality, unhandled edge cases,",
|
|
8663
|
+
" incomplete aspects",
|
|
8664
|
+
"- **Follow-up Questions** \u2014 Ambiguities where intent cannot be",
|
|
8665
|
+
" confidently inferred",
|
|
8666
|
+
"- **Contradictions & Inconsistencies** \u2014 Conflicts between",
|
|
8667
|
+
" requirements, documentation, or stated goals",
|
|
8668
|
+
"",
|
|
8669
|
+
"Number each item within its subsection. Assign a priority. Call out",
|
|
8670
|
+
"interdependencies with open items in other documents using the",
|
|
8671
|
+
"format: `-> Depends on: [FR-001 Open Item #2](../functional/FR-001-slug.md#open-items)`.",
|
|
8672
|
+
"",
|
|
8673
|
+
"The `## Open Items` section is **not optional** \u2014 it appears in every",
|
|
8674
|
+
'document, even if a subsection is empty (write "None identified.").',
|
|
8675
|
+
"",
|
|
8676
|
+
"---",
|
|
8677
|
+
"",
|
|
8678
|
+
"## Reading the Templates and Standards Reference",
|
|
8679
|
+
"",
|
|
8680
|
+
"Before writing any requirement document:",
|
|
8681
|
+
"",
|
|
8682
|
+
"1. **Read the matching template** under `<TEMPLATES_ROOT>` for the",
|
|
8683
|
+
" category specified in the issue (`_template-FR.md`,",
|
|
8684
|
+
" `_template-ADR.md`, etc.). Templates are named",
|
|
8685
|
+
" `_template-{PREFIX}.md`. Every section in the template must",
|
|
8686
|
+
" appear in the final document.",
|
|
8687
|
+
"",
|
|
8688
|
+
"2. **Read `<STANDARDS_REF>`** if the category requires it (especially",
|
|
8689
|
+
" SEC, NFR, INT, ADR, TR). The reference covers OWASP ASVS, ISO",
|
|
8690
|
+
" 25010, BABOK, MADR, Enterprise Integration Patterns, WCAG, and",
|
|
8691
|
+
" related standards that ground the templates.",
|
|
8692
|
+
"",
|
|
8693
|
+
"Templates and the standards reference ship with this skill \u2014 they",
|
|
8694
|
+
"are the same files for every project that adopts the bundle.",
|
|
8695
|
+
"",
|
|
8696
|
+
"---",
|
|
8697
|
+
"",
|
|
8698
|
+
"## Maintaining the Registry Index",
|
|
8699
|
+
"",
|
|
8700
|
+
"Each category directory contains a `README.md` (or `_index.md`,",
|
|
8701
|
+
"depending on project convention) that lists every requirement in",
|
|
8702
|
+
"that category. **After writing any new requirement document, update",
|
|
8703
|
+
"the category index:**",
|
|
8704
|
+
"",
|
|
8705
|
+
"1. Read the index file in the same directory as the new requirement.",
|
|
8706
|
+
"2. Add a row to the requirements table with: ID (linked to the",
|
|
8707
|
+
" file), Title, Status, Priority, Last Updated date.",
|
|
8708
|
+
"3. Insert the row in sequence-number order.",
|
|
8709
|
+
"4. If the index contains a placeholder message, remove it.",
|
|
8710
|
+
"",
|
|
8711
|
+
"If the project has not seeded category READMEs yet, generate one",
|
|
8712
|
+
"from `_template-category-README.md` (shipped with this skill) and",
|
|
8713
|
+
"commit it alongside the requirement document.",
|
|
8714
|
+
"",
|
|
8715
|
+
"---",
|
|
8716
|
+
"",
|
|
8717
|
+
"## Agent Loop",
|
|
8718
|
+
"",
|
|
8719
|
+
"Run this loop exactly once per session. Never start a second issue.",
|
|
8720
|
+
"",
|
|
8721
|
+
"1. Claim one open `req:write` issue (also carries `type:requirement`",
|
|
8722
|
+
" and a `tier:*` label).",
|
|
8723
|
+
"2. Transition `status:ready` \u2192 `status:in-progress` and create the",
|
|
8724
|
+
" branch per your project's branch-naming convention.",
|
|
8725
|
+
"3. Execute the write phase below.",
|
|
8726
|
+
"4. Commit, push, open a PR, and close the issue per your project's",
|
|
8727
|
+
" PR workflow. Closing the PR transitions the issue to",
|
|
8728
|
+
" `status:done` per the standard label conventions.",
|
|
8729
|
+
"",
|
|
8730
|
+
"---",
|
|
8731
|
+
"",
|
|
8732
|
+
"## The `req:write` Phase",
|
|
8733
|
+
"",
|
|
8734
|
+
"**Goal:** Read the proposal that produced this issue, write a single",
|
|
8735
|
+
"requirement document under `<REQUIREMENTS_ROOT>`, and update the",
|
|
8736
|
+
"category index.",
|
|
8737
|
+
"",
|
|
8738
|
+
"**Budget:** Read the issue body, the named proposal file under",
|
|
8739
|
+
"`<RESEARCH_REQUIREMENTS_ROOT>`, the matching category template under",
|
|
8740
|
+
"`<TEMPLATES_ROOT>`, and `<STANDARDS_REF>` if the category needs it.",
|
|
8741
|
+
"Write one requirement document and one category-index update. No web",
|
|
8742
|
+
"searches.",
|
|
8743
|
+
"",
|
|
8744
|
+
"### Steps",
|
|
8745
|
+
"",
|
|
8746
|
+
"1. **Parse the issue.** The `req:write` issue body must include:",
|
|
8747
|
+
" - **Category** (`BR`/`FR`/`NFR`/`TR`/`ADR`/`SEC`/`DR`/`INT`/`OPS`/`UX`/`MT`)",
|
|
8748
|
+
" - **Tier** (`platform`/`industry`/`customer-workflow`/`consumer-app`)",
|
|
8749
|
+
" - **Output Path** under `<REQUIREMENTS_ROOT>/<category-dir>/<PREFIX>-<NNN>-<slug>.md`",
|
|
8750
|
+
" - **Inputs / Read** \u2014 the upstream proposals file and any source",
|
|
8751
|
+
" documents",
|
|
8752
|
+
" If any of these are missing or contradictory, comment on the",
|
|
8753
|
+
" issue, add `status:needs-attention`, and stop without writing.",
|
|
8754
|
+
"",
|
|
8755
|
+
"2. **Read the proposal.** Open the proposals file referenced in the",
|
|
8756
|
+
" issue inputs (under `<RESEARCH_REQUIREMENTS_ROOT>`). Find the",
|
|
8757
|
+
" specific proposal entry that matches this requirement's title and",
|
|
8758
|
+
" category. Treat the proposal as the authoritative source \u2014 do not",
|
|
8759
|
+
" invent fields it omits.",
|
|
8760
|
+
"",
|
|
8761
|
+
"3. **Read the matching template** under `<TEMPLATES_ROOT>` for the",
|
|
8762
|
+
" category. Read `<STANDARDS_REF>` if the category is SEC, NFR,",
|
|
8763
|
+
" INT, ADR, or TR \u2014 these depend on the standards reference for",
|
|
8764
|
+
" correct framing.",
|
|
8765
|
+
"",
|
|
8766
|
+
"4. **Pick the next sequence number.** Scan the target category",
|
|
8767
|
+
" directory under `<REQUIREMENTS_ROOT>` for existing files matching",
|
|
8768
|
+
" `{PREFIX}-NNN-*.md`. Use the next unused three-digit number.",
|
|
8769
|
+
"",
|
|
8770
|
+
"5. **Apply the decision-authority rules.** Default to `Status:",
|
|
8771
|
+
" Draft` for direct-write categories (BR, FR, NFR, SEC, UX). Set",
|
|
8772
|
+
" `Status: Proposed` for ADR and TR documents and frame the",
|
|
8773
|
+
" Recommendation section as a human decision. For DR/MT/INT/OPS",
|
|
8774
|
+
" categories that imply a technology choice, write the requirement",
|
|
8775
|
+
" directly but spin the technology decision off into a separate",
|
|
8776
|
+
" `Proposed` ADR or TR \u2014 record the cross-link in the Open Items",
|
|
8777
|
+
" section of both documents.",
|
|
8778
|
+
"",
|
|
8779
|
+
"6. **Write the document.** Fill every section in the template. For",
|
|
8780
|
+
" sections the proposal does not supply, write `TODO:` plus a brief",
|
|
8781
|
+
" note describing what input is needed, and add a corresponding",
|
|
8782
|
+
" `## Open Items` entry. Never leave a template section out.",
|
|
8783
|
+
"",
|
|
8784
|
+
"7. **Set frontmatter.** At minimum: `title`, `description`, `tier`.",
|
|
8785
|
+
" If the project declares optional frontmatter conventions in",
|
|
8786
|
+
" `docs/project-context.md` (such as `referencedIn.meetings[]`),",
|
|
8787
|
+
" honor them. Otherwise stop at the minimum.",
|
|
8788
|
+
"",
|
|
8789
|
+
"8. **Update the category index.** If the category directory has a",
|
|
8790
|
+
" `README.md` or `_index.md` registry, add a row for the new",
|
|
8791
|
+
" document in sequence order. If no index exists yet, generate one",
|
|
8792
|
+
" from `_template-category-README.md`.",
|
|
8793
|
+
"",
|
|
8794
|
+
"9. **Cross-link upstream.** Add `## Traceability` entries pointing",
|
|
8795
|
+
" to the proposals file (under `<RESEARCH_REQUIREMENTS_ROOT>`),",
|
|
8796
|
+
" the source documents the proposal cited, and any BCM capability",
|
|
8797
|
+
" the requirement supports.",
|
|
8798
|
+
"",
|
|
8799
|
+
"10. **Quality checks.** Before committing, verify:",
|
|
8800
|
+
" - [ ] Frontmatter has `title` and `description` (and `tier` if",
|
|
8801
|
+
" the project uses tier classification)",
|
|
8802
|
+
" - [ ] Title matches the `# Heading` line",
|
|
8803
|
+
" - [ ] File name follows `{PREFIX}-{NNN}-{slug}.md`",
|
|
8804
|
+
" - [ ] Status is `Draft` for direct-write categories or `Proposed`",
|
|
8805
|
+
" for ADR/TR",
|
|
8806
|
+
" - [ ] Every template section is present (use `TODO:` or `Not",
|
|
8807
|
+
" applicable \u2014 <reason>` for unfilled sections)",
|
|
8808
|
+
" - [ ] `## Traceability` exists with at least one upstream link",
|
|
8809
|
+
" - [ ] No technology decisions made in direct-write categories \u2014",
|
|
8810
|
+
" deferred to `Proposed` ADR/TR with cross-links in Open",
|
|
8811
|
+
" Items",
|
|
8812
|
+
" - [ ] `## Open Items` is present with Identified Gaps,",
|
|
8813
|
+
" Follow-up Questions, and Contradictions subsections",
|
|
8814
|
+
" - [ ] ADR/TR documents include a Recommendation section and an",
|
|
8815
|
+
" Open Item flagging the human decision required",
|
|
8816
|
+
" - [ ] Category index updated with a row for the new document",
|
|
8817
|
+
" - [ ] Tier value matches the issue's `tier:*` label",
|
|
8818
|
+
" - [ ] Cross-tier traceability entries exist where the document",
|
|
8819
|
+
" depends on or enables a different tier",
|
|
8820
|
+
"",
|
|
8821
|
+
"11. **Commit and push.** Use a `docs(<category>):` conventional",
|
|
8822
|
+
" commit message. The PR closes the `req:write` issue.",
|
|
8823
|
+
"",
|
|
8824
|
+
"---",
|
|
8825
|
+
"",
|
|
8826
|
+
"## Output Boundaries",
|
|
8827
|
+
"",
|
|
8828
|
+
"This agent writes **only** to:",
|
|
8829
|
+
"",
|
|
8830
|
+
"- `<REQUIREMENTS_ROOT>/<category-dir>/<PREFIX>-<NNN>-<slug>.md` \u2014 one",
|
|
8831
|
+
" requirement document per session",
|
|
8832
|
+
"- `<REQUIREMENTS_ROOT>/<category-dir>/README.md` (or `_index.md`) \u2014",
|
|
8833
|
+
" category index, one row appended per session",
|
|
8834
|
+
"- `<REQUIREMENTS_ROOT>/README.md` (or `_index.md`) \u2014 only if the",
|
|
8835
|
+
" top-level requirements README does not yet exist; generate from",
|
|
8836
|
+
" `_template-requirements-README.md` and stop",
|
|
8837
|
+
"",
|
|
8838
|
+
"The pipeline produces **requirement documents**. It does not write",
|
|
8839
|
+
"BCM capability models, people profiles, company profiles, software",
|
|
8840
|
+
"profiles, scan reports, or proposal files \u2014 those belong to",
|
|
8841
|
+
"specialized upstream/downstream agents.",
|
|
8842
|
+
"",
|
|
8843
|
+
"**Do NOT create:**",
|
|
8844
|
+
"- `req:scan`, `req:draft`, or `req:trace` issues \u2014 those belong to",
|
|
8845
|
+
" the `requirements-analyst` bundle",
|
|
8846
|
+
"- `bcm:*` issues \u2014 those belong to the `bcm-writer` bundle",
|
|
8847
|
+
"- `people:*`, `company:*`, `software:*`, `research:*`, or",
|
|
8848
|
+
" `industry:*` issues \u2014 those belong to their respective bundles",
|
|
8849
|
+
"",
|
|
8850
|
+
"If the proposal surfaces work that needs one of the above, comment",
|
|
8851
|
+
"on the `req:write` issue with the suggested follow-up and let a",
|
|
8852
|
+
"human route it.",
|
|
8853
|
+
"",
|
|
8854
|
+
"---",
|
|
8855
|
+
"",
|
|
8856
|
+
"## Coordination with Other Agents",
|
|
8857
|
+
"",
|
|
8858
|
+
"| Direction | Agent | What |",
|
|
8859
|
+
"|-----------|-------|------|",
|
|
8860
|
+
"| Upstream | `requirements-analyst` | Discovers gaps, drafts proposals, and creates `req:write` issues that this agent picks up |",
|
|
8861
|
+
"| Upstream | `bcm-writer` | Provides BCM capability documents that requirements trace back to via `## Traceability` links |",
|
|
8862
|
+
"| Peer | `meeting-analyst` | Provides meeting transcripts that may inform a requirement's traceability extensions (optional) |",
|
|
8863
|
+
"",
|
|
8864
|
+
"**File boundaries:** Reads `<RESEARCH_REQUIREMENTS_ROOT>` (proposals)",
|
|
8865
|
+
"and the source documents the proposals cite. Writes",
|
|
8866
|
+
"`<REQUIREMENTS_ROOT>` and the category index files. Never edits",
|
|
8867
|
+
"proposals, scan reports, BCM documents, or profiles.",
|
|
8868
|
+
"",
|
|
8869
|
+
"---",
|
|
8870
|
+
"",
|
|
8871
|
+
"## Rules",
|
|
8872
|
+
"",
|
|
8873
|
+
"- **One requirement per session.** Never write two documents in one",
|
|
8874
|
+
" session and never start a second issue.",
|
|
8875
|
+
"- **Templates are authoritative.** Use the shipped template verbatim",
|
|
8876
|
+
" for the category. Every template section must appear in the final",
|
|
8877
|
+
" document.",
|
|
8878
|
+
"- **Decision authority is non-negotiable.** Direct-write categories",
|
|
8879
|
+
" ship as `Draft`. ADR and TR ship as `Proposed` with a Recommendation",
|
|
8880
|
+
" framed for human decision. Mixed-deferral categories spin",
|
|
8881
|
+
" technology choices off into separate `Proposed` documents.",
|
|
8882
|
+
"- **Cite, don't invent.** When the proposal omits a stakeholder,",
|
|
8883
|
+
" metric, threat model entry, or technology option, write `TODO:` and",
|
|
8884
|
+
" flag the issue with `status:needs-attention`.",
|
|
8885
|
+
"- **Trace upstream.** Every requirement links back to its proposal,",
|
|
8886
|
+
" the source documents the proposal cited, and the BCM capability",
|
|
8887
|
+
" it supports (when applicable).",
|
|
8888
|
+
"- **Update the category index every time.** A requirement that",
|
|
8889
|
+
" exists as a file but is missing from its category index is",
|
|
8890
|
+
" invisible to anyone browsing the documentation tree.",
|
|
8891
|
+
"- **Write requirements, not capability models or gap reports.**",
|
|
8892
|
+
" Never open `req:scan`, `req:draft`, `req:trace`, or `bcm:*` issues",
|
|
8893
|
+
" from this pipeline."
|
|
8894
|
+
].join("\n")
|
|
8895
|
+
};
|
|
8896
|
+
var writeRequirementSkill = {
|
|
8897
|
+
name: "write-requirement",
|
|
8898
|
+
description: "Write one formal requirement document (BR / FR / NFR / TR / ADR / SEC / DR / INT / OPS / UX / MT) using the shipped category template and decision-authority rules. Picks up a req:write issue created by the upstream requirements-analyst pipeline (or kicked off ad hoc) and dispatches the requirements-writer agent.",
|
|
8899
|
+
disableModelInvocation: true,
|
|
8900
|
+
userInvocable: true,
|
|
8901
|
+
context: "fork",
|
|
8902
|
+
agent: "requirements-writer",
|
|
8903
|
+
platforms: { cursor: { exclude: true } },
|
|
8904
|
+
referenceFiles: REQUIREMENTS_WRITER_REFERENCE_FILES,
|
|
8905
|
+
instructions: [
|
|
8906
|
+
"# Write Requirement",
|
|
8907
|
+
"",
|
|
8908
|
+
"Write one formal requirement document using the 11-category taxonomy",
|
|
8909
|
+
"(BR, FR, NFR, TR, ADR, SEC, DR, INT, OPS, UX, MT) and the",
|
|
8910
|
+
"decision-authority rules (direct-write vs. propose-only ADR/TR).",
|
|
8911
|
+
"Dispatches the `requirements-writer` agent.",
|
|
8912
|
+
"",
|
|
8913
|
+
"## Usage",
|
|
8914
|
+
"",
|
|
8915
|
+
"/write-requirement <category> <short-title>",
|
|
8916
|
+
"",
|
|
8917
|
+
"Where `<category>` is one of `BR`, `FR`, `NFR`, `TR`, `ADR`, `SEC`,",
|
|
8918
|
+
"`DR`, `INT`, `OPS`, `UX`, `MT`.",
|
|
8919
|
+
"",
|
|
8920
|
+
"Optional extensions in the issue body:",
|
|
8921
|
+
"- `tier: platform | industry | customer-workflow | consumer-app` \u2014",
|
|
8922
|
+
" the architectural tier (default: `platform`)",
|
|
8923
|
+
"- `prefix: <PROJECT_PREFIX>` \u2014 override the default category prefix",
|
|
8924
|
+
" with a project-specific one declared in `docs/project-context.md`",
|
|
8925
|
+
"- `customer: <link-or-slug>` \u2014 link the requirement to a customer",
|
|
8926
|
+
" profile (expected for Customer Workflow / Consumer Application",
|
|
8927
|
+
" tiers in projects that track customer profiles)",
|
|
8928
|
+
"- `proposal: <path>` \u2014 pin the upstream proposal file under",
|
|
8929
|
+
" `<RESEARCH_REQUIREMENTS_ROOT>` (default: derived from the issue",
|
|
8930
|
+
" context)",
|
|
8931
|
+
"- `output: <path>` \u2014 override the default Output Path",
|
|
8932
|
+
"",
|
|
8933
|
+
"## Default Paths",
|
|
8934
|
+
"",
|
|
8935
|
+
"If the project has no override in `docs/project-context.md` or",
|
|
8936
|
+
"`agentConfig.rules`, outputs land under:",
|
|
8937
|
+
"",
|
|
8938
|
+
"- `docs/requirements/<category-dir>/<PREFIX>-<NNN>-<slug>.md`",
|
|
8939
|
+
"- `docs/requirements/<category-dir>/README.md` (registry update)",
|
|
8940
|
+
"- `docs/requirements/README.md` (top-level README, generated on",
|
|
8941
|
+
" first use only)",
|
|
8942
|
+
"",
|
|
8943
|
+
"Templates and the standards reference ship with this skill under",
|
|
8944
|
+
"`_references/templates/` and `_references/standards-and-frameworks.md`.",
|
|
8945
|
+
"",
|
|
8946
|
+
"## Steps",
|
|
8947
|
+
"",
|
|
8948
|
+
"1. Create a `req:write` issue with `type:requirement`,",
|
|
8949
|
+
" `priority:medium`, `status:ready`, and the matching `tier:*` label.",
|
|
8950
|
+
" Body must include the category, tier, output path, and a pointer",
|
|
8951
|
+
" to the upstream proposal (or a direct user description if no",
|
|
8952
|
+
" proposals file exists).",
|
|
8953
|
+
"2. Execute the write phase of the requirements-writer agent.",
|
|
8954
|
+
"3. The agent writes one requirement document, updates the category",
|
|
8955
|
+
" index, opens a PR, and closes the issue.",
|
|
8956
|
+
"",
|
|
8957
|
+
"## Output",
|
|
8958
|
+
"",
|
|
8959
|
+
"- One requirement document under `<REQUIREMENTS_ROOT>` following the",
|
|
8960
|
+
" shipped category template, with `Status: Draft` for direct-write",
|
|
8961
|
+
" categories or `Status: Proposed` for ADR/TR",
|
|
8962
|
+
"- A category-index row pointing at the new document",
|
|
8963
|
+
"- (First-time only) a top-level requirements README derived from",
|
|
8964
|
+
" `_template-requirements-README.md`"
|
|
8965
|
+
].join("\n")
|
|
8966
|
+
};
|
|
8967
|
+
var requirementsWriterBundle = {
|
|
8968
|
+
name: "requirements-writer",
|
|
8969
|
+
description: "Requirements writer agent bundle. Authors formal requirement documents from upstream proposals using the 11-category taxonomy (BR, FR, NFR, TR, ADR, SEC, DR, INT, OPS, UX, MT), the four-tier classification, and decision-authority rules (direct-write vs. propose-only). Ships 13 templates plus a standards-and-frameworks reference.",
|
|
8970
|
+
appliesWhen: () => true,
|
|
8971
|
+
rules: [
|
|
8972
|
+
{
|
|
8973
|
+
name: "requirements-writer-workflow",
|
|
8974
|
+
description: "Describes the requirements-writer pipeline, the req:write phase label, the four tier:* labels, and the boundary with the upstream requirements-analyst and bcm-writer bundles.",
|
|
8975
|
+
scope: AGENT_RULE_SCOPE.ALWAYS,
|
|
8976
|
+
content: [
|
|
8977
|
+
"# Requirements Writer Workflow",
|
|
8978
|
+
"",
|
|
8979
|
+
"Use `/write-requirement <category> <short-title>` to author one",
|
|
8980
|
+
"formal requirement document. The writer runs in a single phase",
|
|
8981
|
+
"tracked by a GitHub issue labeled `req:write` plus the matching",
|
|
8982
|
+
"`tier:*` label. Issues also carry `type:requirement` (declared",
|
|
8983
|
+
"by the upstream `requirements-analyst` bundle).",
|
|
8984
|
+
"",
|
|
8985
|
+
"The pipeline produces **requirement documents only** \u2014 capability",
|
|
8986
|
+
"models are written by the `bcm-writer` agent and gap discovery is",
|
|
8987
|
+
"the responsibility of the `requirements-analyst` agent. The",
|
|
8988
|
+
"writer never opens `req:scan`, `req:draft`, `req:trace`, or",
|
|
8989
|
+
"`bcm:*` issues.",
|
|
8990
|
+
"",
|
|
8991
|
+
"Documents follow the 11-category taxonomy (BR, FR, NFR, TR, ADR,",
|
|
8992
|
+
"SEC, DR, INT, OPS, UX, MT) and the four-tier classification",
|
|
8993
|
+
"(Platform, Industry, Customer Workflow, Consumer Application).",
|
|
8994
|
+
"Templates and a standards-and-frameworks reference ship with the",
|
|
8995
|
+
"skill \u2014 they are the same files for every project that adopts",
|
|
8996
|
+
"the bundle.",
|
|
8997
|
+
"",
|
|
8998
|
+
"Decision-authority rules are non-negotiable: BR / FR / NFR /",
|
|
8999
|
+
"SEC / UX ship as `Status: Draft`; ADR and TR ship as",
|
|
9000
|
+
"`Status: Proposed` with a Recommendation framed for human",
|
|
9001
|
+
"decision; DR / MT / INT / OPS spin technology choices off into",
|
|
9002
|
+
"separate `Proposed` ADR or TR documents.",
|
|
9003
|
+
"",
|
|
9004
|
+
"See the `requirements-writer` agent definition for full workflow",
|
|
9005
|
+
"details, configurable paths, decision-authority rules, and",
|
|
9006
|
+
"phase-by-phase instructions."
|
|
9007
|
+
].join("\n"),
|
|
9008
|
+
platforms: {
|
|
9009
|
+
cursor: { exclude: true }
|
|
9010
|
+
},
|
|
9011
|
+
tags: ["workflow"]
|
|
9012
|
+
}
|
|
9013
|
+
],
|
|
9014
|
+
skills: [writeRequirementSkill],
|
|
9015
|
+
subAgents: [requirementsWriterSubAgent],
|
|
9016
|
+
labels: [
|
|
9017
|
+
{
|
|
9018
|
+
name: "req:write",
|
|
9019
|
+
color: "FEF2C0",
|
|
9020
|
+
description: "Phase: write a formal requirement document using the requirements-writer skill"
|
|
9021
|
+
},
|
|
9022
|
+
{
|
|
9023
|
+
name: "tier:platform",
|
|
9024
|
+
color: "EDEDED",
|
|
9025
|
+
description: "Architectural tier: core platform (shared infrastructure, APIs, auth, tenant isolation)"
|
|
9026
|
+
},
|
|
9027
|
+
{
|
|
9028
|
+
name: "tier:industry",
|
|
9029
|
+
color: "EDEDED",
|
|
9030
|
+
description: "Architectural tier: industry vertical (capabilities not every tenant needs)"
|
|
9031
|
+
},
|
|
9032
|
+
{
|
|
9033
|
+
name: "tier:customer-workflow",
|
|
9034
|
+
color: "EDEDED",
|
|
9035
|
+
description: "Architectural tier: customer-configured workflow (business logic tenants configure within the platform)"
|
|
9036
|
+
},
|
|
9037
|
+
{
|
|
9038
|
+
name: "tier:consumer-app",
|
|
9039
|
+
color: "EDEDED",
|
|
9040
|
+
description: "Architectural tier: consumer application (UI/UX and integrations in external front-ends/systems)"
|
|
9041
|
+
}
|
|
9042
|
+
]
|
|
9043
|
+
};
|
|
9044
|
+
|
|
6272
9045
|
// src/agent/bundles/research-pipeline.ts
|
|
6273
9046
|
var researchAnalystSubAgent = {
|
|
6274
9047
|
name: "research-analyst",
|
|
@@ -8111,6 +10884,7 @@ var BUILT_IN_BUNDLES = [
|
|
|
8111
10884
|
orchestratorBundle,
|
|
8112
10885
|
prReviewBundle,
|
|
8113
10886
|
requirementsAnalystBundle,
|
|
10887
|
+
requirementsWriterBundle,
|
|
8114
10888
|
researchPipelineBundle,
|
|
8115
10889
|
companyProfileBundle,
|
|
8116
10890
|
peopleProfileBundle,
|
|
@@ -11602,6 +14376,7 @@ export {
|
|
|
11602
14376
|
prReviewBundle,
|
|
11603
14377
|
projenBundle,
|
|
11604
14378
|
requirementsAnalystBundle,
|
|
14379
|
+
requirementsWriterBundle,
|
|
11605
14380
|
researchPipelineBundle,
|
|
11606
14381
|
resolveModelAlias,
|
|
11607
14382
|
resolveTemplateVariables,
|