awslabs / awslabs/aidlc-workflows

[Feature]: Separate agent-internal files from human-reviewable artifacts

Open
#413 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.