Add design document support to APS planning framework#30
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 44bc9f7853
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Pull request overview
Adds design documents as a first-class APS planning artefact (stored in designs/), including templates, lint rules (warnings W014–W016), CLI integration, scaffold support, docs updates, and an example design.
Changes:
- Introduces a new design doc template/format and updates docs to describe the design workflow.
- Adds design-doc linting rules (bash + PowerShell) and integrates
.design.mddiscovery into the linter/CLI. - Updates scaffolding/installation scripts and adds an example design doc linked from the user-auth example.
Reviewed changes
Copilot reviewed 20 out of 22 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| templates/design.template.md | New repo-level design doc template. |
| scaffold/designs/.design.template.md | New scaffolded design template for new projects. |
| lib/rules/design.sh | New bash lint rules for design docs (W014–W016). |
| lib/rules/Design.psm1 | New PowerShell lint rules for design docs (W014–W016). |
| lib/lint.sh | Adds .design.md discovery and dispatch to lint_design. |
| lib/Lint.psm1 | Adds .design.md discovery and dispatch to Invoke-ApsDesignLint. |
| bin/aps | Sources new design.sh rules module. |
| bin/aps.ps1 | Imports new Design.psm1 rules module. |
| scaffold/init.sh | Bootstrap scaffold now creates designs/ and installs the design template. |
| scaffold/install.ps1 | PowerShell installer now creates designs/ and downloads the design template + rule modules. |
| plans/aps-rules.md | Documents designs/ location and guidance for design docs. |
| scaffold/plans/aps-rules.md | Same as above for scaffolded guidance file. |
| aps-planning/reference.md | Adds design doc patterns + warning codes to reference docs. |
| scaffold/aps-planning/reference.md | Same reference updates for scaffolded skill docs. |
| aps-planning/SKILL.md | Updates skill to consider design docs and normalisation guidance. |
| scaffold/aps-planning/SKILL.md | Same skill updates for scaffolded version. |
| docs/workflow.md | Adds design doc step to workflow narrative. |
| docs/getting-started.md | Adds design doc option to getting-started flow + file layout. |
| README.md | Adds design template to template list and file layout snippet. |
| AGENTS.md | Notes design docs as part of APS artefacts. |
| examples/user-auth/index.aps.md | Links the new example design doc. |
| examples/user-auth/designs/2025-01-05-auth-architecture.design.md | New example design document. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
examples/user-auth/designs/2025-01-05-auth-architecture.design.md
Outdated
Show resolved
Hide resolved
Introduces a standardized `designs/` folder at the project root for technical/architectural design documents. Designs capture the "why this approach" thinking before committing to modules and work items. Key changes: - New design template (templates/design.template.md) - Scaffold creates designs/ with template on init and update - Linter detects and validates *.design.md files (warnings only, no errors) - Agent guidance includes accept-then-normalise rule for free-form designs - Example design doc added to user-auth example - All docs, rules, and references updated with designs/ in file layouts https://claude.ai/code/session_01MJJzMEySiQmiCoUEw73qte
- Fix design path matching to handle root-level designs/ paths (bash and PowerShell) - Require both Field header and Status row for W016 check - Add design rule files to all CLI manifests (scaffold/install, scaffold/update, lib/scaffold.sh, lib/Scaffold.psm1 etc.) - Fix grammar: "a Action Plan" → "an Action Plan" - Fix broken module links in example design doc Authored-By: Aneki (joshuaboys)
joshuaboys
force-pushed
the
claude/add-designs-folder-qwjzs
branch
from
44bc9f7 to
5465707
Compare
Review Feedback AddressedCode Changes (1 commit pushed)
Replied (no code change)
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5465707242
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| # Also scan designs/ when the target is specifically plans/ | ||
| # (find_aps_files already recurses, so this only adds the sibling designs/ dir) | ||
| if [[ "$target" == "plans" || "$target" == "plans/" ]]; then |
There was a problem hiding this comment.
The new sibling-scan only runs when target is exactly plans or plans/, so aps lint ./plans, aps lint ../repo/plans, or absolute .../plans paths never include design docs and silently skip W014–W016. In this commit, cmd_lint advertises design linting as part of plans linting, but this literal string check means the behavior only works for one invocation form; please derive the sibling designs path from the provided target directory instead of hard-coding designs in CWD (the same pattern appears in lib/Lint.psm1).
Useful? React with 👍 / 👎.
Summary
This PR introduces design documents as a first-class artefact in the APS planning framework. Design docs capture architectural thinking and approach decisions before committing to modules and work items, enabling better review and comparison of alternatives for complex, multi-module work.
Key Changes
New design document format (
designs/YYYY-MM-DD-slug.design.md):templates/design.template.mdandscaffold/designs/.design.template.mdValidation rules for design docs (warnings only, free-form designs accepted):
## Problemsection## Designsectionlib/rules/design.sh(bash) andlib/rules/Design.psm1(PowerShell)CLI integration:
bin/apsandbin/aps.ps1to source design validation ruleslib/lint.shandlib/Lint.psm1to detect and lint.design.mdfilesplans/directoryDocumentation updates:
plans/aps-rules.mdandscaffold/plans/aps-rules.mdaps-planning/reference.mdandaps-planning/SKILL.mdwith design workflowScaffold improvements:
scaffold/init.shandscaffold/install.ps1now createdesigns/directory and copy templateplans/in new projectsExample design document:
examples/user-auth/designs/2025-01-05-auth-architecture.design.mddemonstrating JWT + refresh token strategy for authenticationImplementation Details
designs/at project root (peer toplans/), not nested within plans