diff --git a/docs/plays/aiswec_play-outline.md b/docs/plays/aiswec_play-outline.md index 0ee1c0b..6149c1c 100644 --- a/docs/plays/aiswec_play-outline.md +++ b/docs/plays/aiswec_play-outline.md @@ -34,7 +34,7 @@ Play series: AI4SDLC | Status: Draft | Target publish: Late 2026 This play is the AI-SWEC question set — the full pre-event (B-xx) and post-event (P-xx) instrument — with guidance on how to conduct the assessment and use the responses to build an ADR. -Read the [Defining Your Why](../../docs/plays/defining_your_why_play-outline.md) play first. That play explains the Before/Measure/After arc, the Go/Slow/No-Go decision framework, and when and why to use AI-SWEC. This play is the instrument itself. +Read the [Defining Your Why](defining_your_why_play-outline.md) play first. That play explains the Before/Measure/After arc, the Go/Slow/No-Go decision framework, and when and why to use AI-SWEC. This play is the instrument itself. --- @@ -359,7 +359,7 @@ DORA — Team Process Metrics: *How AI-SWEC responses populate the ADR. The B-xx questions build it; the P-xx questions complete it.* -The ADR is initiated at the Go/Slow/No-Go decision point — before the pilot begins. See the [Defining Your Why](../../docs/plays/defining_your_why_play-outline.md) play, Section 6.1 for the ADR Jumpstart fields and initiation logic. This section shows which AI-SWEC questions feed which ADR fields. +The ADR is initiated at the Go/Slow/No-Go decision point — before the pilot begins. See the [Defining Your Why](defining_your_why_play-outline.md) play, Section 6.1 for the ADR Jumpstart fields and initiation logic. This section shows which AI-SWEC questions feed which ADR fields. | ADR Field | Pre-Event Source (B-xx) | Post-Event Source (P-xx) | | --- | --- | --- | @@ -374,7 +374,7 @@ The ADR is initiated at the Go/Slow/No-Go decision point — before the pilot be | Human Impact | — | P-19, P-22, P-15, P-23, P-34, P-35 | | Solution Fit Assessment | — | P-27, P-12, P-13, P-16, P-17 | -See the [ADR template](../../docs/resources/ArchitecturalDecisionRecord.md) in docs/resources. +See the [ADR template](../resources/ArchitecturalDecisionRecord.md) in docs/resources. > **Author notes — Section 7:** > @@ -425,11 +425,11 @@ See the [ADR template](../../docs/resources/ArchitecturalDecisionRecord.md) in d **Related Plays:** -- [Defining Your Why](../../docs/plays/defining_your_why_play-outline.md) — read first; the adoption decision framework, Before/Measure/After arc, Go/Slow/No-Go, and ADR Jumpstart +- [Defining Your Why](defining_your_why_play-outline.md) — read first; the adoption decision framework, Before/Measure/After arc, Go/Slow/No-Go, and ADR Jumpstart - [AI Autonomy Continuum](ai-autonomy_continuum_play.md) — pattern selection; agentic governance readiness; P1-P4 patterns - [AI Autonomy Implementation Guide](ai-autonomy-implementation-guide.md) — pattern-specific readiness checklists - [Fundamentals for Designing an AI-Augmented Tool Chain](fundamentals-play.md) — hosting models, tool selection -- [AI Workflow Design and Governance](ai_sdlc_workflows_play.md) — workflow governance, skills file governance +- [AI Workflow Design and Governance](ai_sdlc_workflows-play.md) — workflow governance, skills file governance **Key References:** @@ -468,7 +468,7 @@ This play is the structured assessment instrument behind the AI4SDLC adoption de - **Copyright:** Copyright block is at the top of the document and on Sections 5 and 6 headers. Do not remove or weaken these notices in prose. - **Verification required:** All B-xx and P-xx question IDs and text must be verified against `AI-SWEC_Beta_DecisionTool.xlsx` in `local_working_files/defining_why/` before prose draft. The August 2025 PDF is the source for this outline; the Excel is authoritative. - **No duplication with Defining Your Why.** This play does not explain the Before/Measure/After arc, Go/Slow/No-Go logic, adoption prerequisites, DORA metrics, field examples, or the ADR initiation point. Reference and link to the Defining Your Why play for all of that. -- **Link paths (update when moved to docs/plays/):** Links in this file are set for `local_working_files/defining_why/`. When moved to `docs/plays/`, shorten as follows: `../../docs/plays/defining_your_why_play-outline.md` → `defining_your_why_play-outline.md`; `../../docs/resources/ArchitecturalDecisionRecord.md` → `../resources/ArchitecturalDecisionRecord.md`. Companion play links (Section 10) will also need `../../docs/plays/` prefix removed once those plays exist in docs/plays/. +- **Link paths:** This file now lives in `docs/plays/`, and its links are set for that location. Relative links to sibling plays are bare filenames; links to `docs/resources/` are prefixed `../resources/`. - **No score, no maturity model.** Never frame sections as scoring. Never imply a threshold that constitutes passing. - **Online tool:** Describe as "in development" with intended capability. Do not imply availability. - **Framework evolution:** AI-SWEC is Beta as of August 2025. State that the question set may be refined. diff --git a/docs/plays/code-gen-play.md b/docs/plays/code-gen-play.md index ff033a0..8ed6159 100644 --- a/docs/plays/code-gen-play.md +++ b/docs/plays/code-gen-play.md @@ -450,7 +450,7 @@ These variations can affect everything from code style and verbosity to security - **Provide role-specific tradecraft guidance** for approved tools, including prompt examples, review checklists, and lessons learned from secure use in operational contexts. -> For systemic risk guidance, see the upcoming [Risk Reference Companion](../resources/risk-reference.md) where “Tool Drift”, “Model Fragmentation”, and "Prompt Misuse" are addressed in more depth. +> For systemic risk guidance, see the upcoming Risk Reference Companion, where “Tool Drift”, “Model Fragmentation”, and "Prompt Misuse" are addressed in more depth. ---- diff --git a/docs/plays/defining_your_why_play-outline.md b/docs/plays/defining_your_why_play-outline.md index 7b33029..51f5d69 100644 --- a/docs/plays/defining_your_why_play-outline.md +++ b/docs/plays/defining_your_why_play-outline.md @@ -443,7 +443,7 @@ The AI-SWEC B-xx question set maps directly to the Context, Decision, and Conseq - [AI Autonomy Continuum](ai-autonomy_continuum_play.md) — pattern selection, autonomy health index, shadow AI governance - [AI Autonomy Implementation Guide](ai-autonomy-implementation-guide.md) — pattern-specific readiness checklists, health metrics - [Fundamentals for Designing an AI-Augmented Tool Chain](fundamentals-play.md) — hosting models, trust architecture -- [AI Workflow Design and Governance](ai_sdlc_workflows_play.md) — workflow governance, review gates, skills file governance +- [AI Workflow Design and Governance](ai_sdlc_workflows-play.md) — workflow governance, review gates, skills file governance - [Requirements Engineering with AI Assistance](requirements_engineering_play.md) — maturity indicators, traceability - [AI-Augmented Testing](testing-play.md) — test coverage metrics, defect escape rate, test-from-code anti-pattern - [Code Completion and Generation](code-gen-play.md) — DevSecOps baseline requirements, code generation risk diff --git a/docs/plays/documentation-play.md b/docs/plays/documentation-play.md index d9aac83..d2b324e 100644 --- a/docs/plays/documentation-play.md +++ b/docs/plays/documentation-play.md @@ -456,7 +456,7 @@ Teams new to AI-assisted documentation should adopt an incremental approach: Reusable templates for common documentation artifacts (ADRs, API specs, runbooks, release notes) are being developed for the AI4SDLC resource library. These will include prompt patterns and validation checklists aligned with the GenAI patterns in this play. -*See [Resources](../resources/) for available templates as they are published.* +*See the [Architectural Decision Record](../resources/ArchitecturalDecisionRecord.md) and [play template](../resources/template.md) for what is available so far.* --- diff --git a/docs/plays/protovibe_play.md b/docs/plays/protovibe_play.md index 2137b08..cc46035 100644 --- a/docs/plays/protovibe_play.md +++ b/docs/plays/protovibe_play.md @@ -39,7 +39,7 @@ Naming the artifact matters more than naming the activity. The governance questi ### 1.2 Comprehension Is Its Own Axis -Proto-vibing is not a point on the task-level autonomy scale in the [AI & Agentic Workflow Design and Governance](ai_sdlc_workflows_play.md) play. That scale governs what an agent is *permitted* to do. Comprehension describes what the human *understood*. Every autonomy level presumes a human who comprehends, so a developer at Level 1 who applies a draft without reading it has satisfied the framework and learned nothing. That play already flags the same hazard when it warns that approving outputs without meaningful evaluation turns human-in-the-loop review into a formality. +Proto-vibing is not a point on the task-level autonomy scale in the [AI & Agentic Workflow Design and Governance](ai_sdlc_workflows-play.md) play. That scale governs what an agent is *permitted* to do. Comprehension describes what the human *understood*. Every autonomy level presumes a human who comprehends, so a developer at Level 1 who applies a draft without reading it has satisfied the framework and learned nothing. That play already flags the same hazard when it warns that approving outputs without meaningful evaluation turns human-in-the-loop review into a formality. Agent count is likewise orthogonal. One agent whose output nobody reads produces a protovibe. Twelve agents orchestrated against a spec, with an engineer owning the design, do not. Scaling the mechanism does not change the comprehension question, though it does raise the containment requirement (Section 6). @@ -179,7 +179,7 @@ Proto-vibing is groundbreaking potential with limitations and challenges. Run th ### Related Plays and Resources - [Leading Practices for Code Completion and Generation](code-gen-play.md) -- [AI & Agentic Workflow Design and Governance](ai_sdlc_workflows_play.md) +- [AI & Agentic Workflow Design and Governance](ai_sdlc_workflows-play.md) - [AI Autonomy Continuum](ai-autonomy_continuum_play.md) - [Requirements Engineering](requirements_engineering_play.md) - [Architectural Decision Records](../resources/ArchitecturalDecisionRecord.md) diff --git a/mkdocs.yml b/mkdocs.yml index ea0a1dd..1bdfe75 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,7 +41,7 @@ nav: - AI Workflow Design: plays/ai_sdlc_workflows-play.md - IDE Security: plays/ide-security.md - Early Adopter Stories: - - Army SMDCoE: plays/army-smdcoe-play.md + - Army SMDCoE: stories/army-smdcoe.md - Patterns: - Human-Machine Interaction Patterns: plays/human-machine-patterns.md - Practices: