awslabs / awslabs/aidlc-workflows
[Feature]: Separate agent-internal files from human-reviewable artifacts
- Dominant language
- TypeScript
- Stars
- 4.6k
- Forks
- 827
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 158
Description
### Description
The `aidlc-docs` directory mixes agent-internal state files with the actual deliverables a human wants to review. When navigating the output, it's very difficult to distinguish what's "for the agent" (working memory, learning selections, intermediate questions) from what's "for the human" (requirements, designs, code plans, summaries).
Humans cannot quickly identify what they should be reviewing, and navigating the file tree requires understanding AIDLC internals to filter signal from noise. This makes AIDLC output feel overwhelming rather than useful.
The desired outcome is clear separation between agent-internal state and human-reviewable artifacts. A user should be able to open the `aidlc-docs` directory and immediately identify the deliverables they need to review without wading through agent working files.
One possible approach (non-prescriptive) could be moving agent-internal files into hidden/dot directories (e.g., `.agent-state/`) while keeping human-reviewable artifacts in clearly named, prominent locations. But the implementation is up to the maintainers — the key outcome is that users can easily find and review the artifacts that matter to them.
### Use Case
When a developer uses AIDLC to build or evolve a project, they need to review the generated artifacts (requirements, designs, code plans) as part of their normal workflow. Currently, finding those artifacts requires mentally filtering out agent-internal files (JSON state, memory, questions) that are irrelevant to the review process. This slows down the human-in-the-loop review cycle and makes the AIDLC output feel unapproachable — especially for developers new to the tool who don't know which files matter.
### Version
v2 (alpha)
### Area
Documentation
### Additional Context
Example in `aidlc-docs/inception/requirements-analysis/`:
```
.learnings-selections-feature.json ← agent internal
.learnings-selections.json ← agent internal
memory.md ← agent internal
requirements-analysis-questions.md ← agent internal
sharing-link-questions.md ← agent internal
requirements.md ← HUMAN-REVIEWABLE ARTIFACT
bug-report.md ← HUMAN-REVIEWABLE ARTIFACT
```
Example in `aidlc-docs/construction/code-generation/`:
```
.learnings-selections-bugfix.json ← agent internal
.learnings-selections-perf.json ← agent internal
.learnings-selections.json ← agent internal
memory.md ← agent internal
```
Top-level agent plumbing directories (`.aidlc-hooks-health/`, `.aidlc-sensors/`, `.aidlc-stop-hook/`) add further noise to the file tree.
Contributor guide
Research direction
Start by reviewing the file examples under aidlc-docs/inception/requirements-analysis/ and aidlc-docs/construction/code-generation/, then inspect the top-level .aidlc-hooks-health/, .aidlc-sensors/, and .aidlc-stop-hook/ directories. Determine how agent-internal state can be separated from human-reviewable artifacts without losing workflow behavior. Done means users can open aidlc-docs and immediately identify requirements, designs, code plans, and summaries without filtering agent files.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100