feat(aidd-dev): assess coding-agent development workflow readiness #954

Problem

AIDD can assess intrinsic codebase quality through the seven read-only 04-audit pillars, and it is adding explicit capabilities around project context and contributor validation. It still has no focused assessment of whether a coding agent can establish, operate, validate, and recover within a repository's development workflow using authoritative repository evidence, without relying on undocumented human knowledge.

A repository may have sound code, tests, Rules, and organized context while still hiding operational prerequisites: a service must be started first, a database must be initialized, generation must precede a build, configuration is required, or failures do not expose a deterministic next step. The gap is therefore not a generic Agentic Readiness framework. It is the missing assessment of the tacit knowledge an agent still needs to work safely and reproducibly in the repository.

For example, repository evidence may show a PostgreSQL dependency and a required DATABASE_URL, without exposing an authoritative, reproducible database initialization path. The finding should be that initialization cannot be established from repository evidence, not an invented command.

Outcome

A read-only, evidence-backed assessment can answer whether the repository's development workflow is sufficiently reproducible, discoverable, and recoverable for a coding agent. It should report a clean/ready result when no relevant problem is found and distinguish missing evidence from a confirmed defect.

Scope

• Add a narrowly scoped repository-workflow readiness assessment, using the existing aidd-dev:04-audit reporting seam or another architecture-consistent seam if the current implementation requires it. Do not prescribe a new skill or audit pillar unless the architecture proves that necessary.
• Assess development reproducibility: dependency and runtime setup, required configuration, services, containers/devcontainers, database initialization, migrations, fixtures/seeds, generation, build, and application start where repository evidence makes them relevant.
• Assess operational discoverability of essential development operations such as install, build, start, unit tests, lint, format, generation, integration-test setup, and contributor validation workflows.
• Assess agent recoverability/developer debuggability: whether failures expose enough deterministic, repository-evidenced information for an agent to diagnose the problem and identify a reasonable next step.
• Base findings on documentation, contribution files, manifests, scripts, task runners, CI, containers, environment templates, source/configuration, tests, and executable tooling. Classify findings as confirmed, missing, ambiguous, conflicting, non-reproducible, or not assessable from repository evidence as appropriate.
• Cite concrete repository evidence for each finding, preserve conflicting authoritative sources instead of choosing silently, and never invent commands, procedures, or undocumented team practices.
• Keep the result semantics evidence-based: support clean/ready, warning/partially ready, blocked, and not assessable outcomes as appropriate, without introducing a universal numeric score.
• Keep the implementation read-only by default and reuse existing audit report/findings conventions where applicable.

Acceptance criteria

• The assessment works without requiring a current feature, diff, or proposed change.
• The default assessment is read-only and does not modify repository code, configuration, documentation, Rules, or context artifacts.
• Development-environment requirements evidenced by the repository are assessed for missing, ambiguous, conflicting, or non-reproducible setup paths.
• Essential development operations are assessed for authoritative discoverability without requiring every repository to use the same tools, files, or workflow.
• Development failures are assessed for sufficient repository-evidenced diagnostics and reasonable recovery information where applicable.
• The report distinguishes confirmed requirements, missing information, ambiguity, conflict, non-reproducibility, and not assessable from repository evidence.
• Conflicting authoritative sources are surfaced rather than silently resolved.
• Every finding cites concrete repository evidence and does not rely only on generic LLM expectations.
• The assessment never invents undocumented commands, procedures, prerequisites, or team practices.
• A repository with no relevant finding produces a clear clean/ready result without manufactured recommendations.
• The assessment remains separate from the existing 04-audit quality pillars, 03-assert, and 06-test responsibilities.
• The assessment remains separate from feat(aidd-context): audit an existing rule corpus for conflicts, duplication and drift #792 Rule-corpus consistency/context efficiency, feat(aidd-context): audit the project context architecture and ownership #793 context architecture and ownership, feat(aidd-dev): audit codebase compliance against project rules #864 Rule-to-existing-codebase conformance, and feat(aidd-dev): derive validation from repository contributor workflows #928 feature-specific contributor-validation selection.
• The implementation does not introduce a universal readiness score, automatic remediation, or a production observability audit.
• Where implemented through 04-audit, the assessment reuses its existing report/findings infrastructure and does not change unrelated audit contracts.

Prior art in this repo

• 04-audit/SKILL.md#L7-L33 owns the read-only seven-pillar audit of intrinsic codebase quality; the proposed capability assesses repository development-workflow readiness instead.
• 00-onboard/SKILL.md#L7-L28 guides a project's journey and routes next steps, but does not assess whether the development environment is reproducible or recoverable from repository evidence.
• 01-plan/SKILL.md#L7-L27, 03-assert/SKILL.md, 06-test/SKILL.md, and #928 establish adjacent planning, assertion, testing, and contributor-validation boundaries. feat(aidd-dev): derive validation from repository contributor workflows #928 selects validation applicable to a specific change; this proposal assesses the repository's general ability to expose that workflow to an agent.
• #792 owns Rule-corpus conflicts, duplication, overlap, drift, and context efficiency.
• #793 owns cross-artifact context architecture, ownership, loading role, and source-of-truth concerns.
• #864 owns repository-wide conformance of existing code to applicable project Rules.
• #928 derives the validation contract applicable to a specific change from authoritative contributor workflows; it is complementary prior art, not the same assessment.
• CONTRIBUTING.md and the detailed contribution form require an issue-first, scoped change with observable acceptance criteria before implementation.

Out of scope

• General code-quality, architecture, security, dependency, performance, test-quality/coverage/flakiness, and UI auditing owned by the existing 04-audit pillars.
• Rule conflicts, duplication, overlap, drift, and context efficiency owned by feat(aidd-context): audit an existing rule corpus for conflicts, duplication and drift #792.
• Context-artifact ownership, placement, loading mode, and source-of-truth auditing owned by feat(aidd-context): audit the project context architecture and ownership #793.
• Code-to-Rule conformance owned by feat(aidd-dev): audit codebase compliance against project rules #864.
• Feature-specific contributor-validation command selection owned by feat(aidd-dev): derive validation from repository contributor workflows #928.
• Coding assertions owned by 03-assert and developer-side automated testing/user-journey testing owned by 06-test.
• Automatic remediation, rewriting repository documentation/configuration, or changing Rules/context artifacts.
• Universal numeric readiness scoring, token/cost benchmarking, model benchmarking, LLM comparison, or a generic external Agent Readiness framework.
• Production observability, SRE maturity, logging architecture, performance monitoring, or reproduction of an arbitrary CI matrix.
• Guessing undocumented human/team knowledge or treating absence of evidence alone as proof of a defect.