Skip to content

docs: add working-with-aidlc interaction guide and writing-inputs documents#121

Open
harmjeff wants to merge 12 commits intoawslabs:mainfrom
harmjeff:feature/instructions
Open

docs: add working-with-aidlc interaction guide and writing-inputs documents#121
harmjeff wants to merge 12 commits intoawslabs:mainfrom
harmjeff:feature/instructions

Conversation

@harmjeff
Copy link
Contributor

@harmjeff harmjeff commented Mar 16, 2026

Summary

  • Adds working-with-aidlc.md — a practical guide covering interaction patterns, tips, and examples drawn from real workshop experience, covering the full workflow from Inception through Construction
  • Adds writing-inputs/ folder with guides and templates for preparing Vision and Technical Environment documents before starting a project
  • Updates README.md Additional Resources table with a reference to working-with-aidlc.md

Test plan

  • Verify all links in README.md pointing to working-with-aidlc.md resolve correctly
  • Verify all internal links within working-with-aidlc.md (e.g. to writing-inputs/ files) resolve correctly
  • Review writing-inputs/inputs-quickstart.md for greenfield and brownfield quick-start paths
  • Review writing-inputs/vision-document-guide.md and writing-inputs/technical-environment-guide.md for completeness

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

harmjeff and others added 2 commits March 16, 2026 17:54
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
@harmjeff harmjeff requested a review from raj-jain-aws March 19, 2026 20:47
@harmjeff harmjeff requested review from a team as code owners March 20, 2026 18:00
@harmjeff harmjeff requested a review from wilmatos March 20, 2026 21:14
Copy link
Member

@scottschreckengaust scottschreckengaust left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider placing files under docs

Move working-with-aidlc.md to docs/WORKING-WITH-AIDLC.md and consolidate
all writing-inputs guides under docs/writing-inputs/. Prefix all example
files with 'example-' for clarity and consistency. Update all internal
references to reflect new locations.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@harmjeff
Copy link
Contributor Author

All @scottschreckengaust requests are completed

harmjeff and others added 2 commits March 25, 2026 09:44
Co-authored-by: Scott Schreckengaust <scottschreckengaust@users.noreply.github.com>
Co-authored-by: Scott Schreckengaust <scottschreckengaust@users.noreply.github.com>
spraja08
spraja08 previously approved these changes Mar 25, 2026
Copy link
Contributor

@spraja08 spraja08 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed. Good to go.

Co-authored-by: Scott Schreckengaust <scottschreckengaust@users.noreply.github.com>
harmjeff and others added 3 commits March 25, 2026 12:38
Co-authored-by: Scott Schreckengaust <scottschreckengaust@users.noreply.github.com>
Co-authored-by: Scott Schreckengaust <scottschreckengaust@users.noreply.github.com>
Co-authored-by: Scott Schreckengaust <scottschreckengaust@users.noreply.github.com>
Copy link
Member

@scottschreckengaust scottschreckengaust left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Copy link
Contributor

@Kalindi-Dev Kalindi-Dev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@harmjeff
This is nitpicky and can be added to subsequent releases:

  1. WORKING-WITH-AIDLC.md:118 — "If your tool offers a 'compact context' prompt mid-workflow, always decline it" is strong advice that may become outdated as context management in AI tools evolves. Consider softening to something like "compaction mid-workflow is generally less reliable than a clean
    reset."

  2. WORKING-WITH-AIDLC.md:555 — "This flow takes a few extra minutes compared to directly editing a file." Contains an implicit time estimate. Minor, but could be rephrased as "This flow takes extra steps compared to directly editing a file."

Looks good to me otherwise.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants