make-dev-utilities#135
Conversation
…ocal dev entrypoint]
… surface for common maintainer workflows]
…demoting noisy internal commands]
…or the supported workflow]
|
Implemented story Changes in this iteration:
Validation run locally:
|
|
Implemented story \ on commit . Changes in this iteration:
[MDX] generated files in 43.54150000000004ms Route (app) ○ (Static) prerendered as static content Wrote /Users/abdifamily/work/learn-agent-factories/.claude/worktrees/make-dev-utilities/.next/verify-build-source-fingerprint (9876379…).
Validation run locally:
|
|
Mergeability follow-up on head |
|
Mergeability follow-up on head
No code changes were needed in this iteration; the remaining blocker is active GitHub runner scheduling within the fresh 15-minute wait window. |
|
Mergeability follow-up on head
No code changes were needed in this iteration; the branch remains in mergeability wait-state pending the live required checks. |
|
Mergeability follow-up on head
No code changes were needed in this iteration; the branch remains in required-CI follow-up while the fresh rerun is still inside the allowed wait window. |
|
Mergeability follow-up on head
No code changes were needed in this iteration; the branch remains in mergeability wait-state pending the live required checks. |
|
Mergeability follow-up on head
No code changes were needed in this iteration; the branch remains in mergeability wait-state pending the live required checks. |
|
Mergeability follow-up on head
No code changes were needed in this iteration; the current branch is waiting on the fresh required checks. |
|
Mergeability follow-up on head
No code changes were needed in this iteration; the branch remains in mergeability follow-up while the refreshed required checks run. |
|
Mergeability follow-up on head
No code changes were needed in this iteration; the branch remains in required-CI follow-up while the live run progresses. |
|
Mergeability follow-up on head
No code changes were needed in this iteration; the remaining blocker is live required CI on the rerun. |
|
Mergeability follow-up on head
No code changes were needed in this iteration; the remaining blocker is live required CI on the fresh rerun. |
|
Mergeability follow-up on head :
No code changes were needed in this iteration; the remaining blocker is the fresh required CI matrix, which is still inside the mandatory 15-minute wait window. |
|
Mergeability follow-up on head
No code changes were needed in this iteration; the remaining blocker is the fresh required CI matrix, which is still inside the mandatory 15-minute wait window. |
|
Mergeability follow-up on head
No code changes were needed in this iteration; the remaining blocker is the fresh required CI matrix, which is still inside the mandatory 15-minute wait window. |
1 participant
{
"project": "Model Atlas — Developer Utilities Command Surface",
"branchName": "make-dev-utilities",
"description": "Repair the broken generated-content-aware local developer workflow and reduce the default Make and Bun command surface to a small, consistent set of maintainer commands for local run, build, test, lint, validate, generate, help, and CI.",
"context": {
"customerAsk": "Fix
make dev, which broke after the project switched to generating many pages and derived artifacts. Clean up theMakefileandpackage.jsoncommand surface so developers have clear commands for code generation, linting, validation, testing, local build, and local run without needing to choose from many phase-specific test and verification commands.","problem": "The repository currently mixes top-level developer workflows with many low-level generation and phase-specific verification commands.
make devdoes not clearly reflect the generated-content prerequisites the site now depends on, and a maintainer cannot infer a simple happy path for local work from the command surface itself.","solution": "Define one supported maintainer workflow across
Makefileandpackage.json:dev,build,test,lint,validate,generate,ci, andhelp. Makedevandbuildrun the required generated-content preparation steps, keep specialized verifiers available only as internal or advanced utilities, and add command-level verification so generated-page changes cannot silently break the supported local workflow again."},
"acceptanceCriteria": [
"
make devprepares the generated-content prerequisites required by the current site and starts the local docs app without requiring a maintainer to run extra generation commands first.","The supported top-level command surface is limited to a short maintainer workflow covering local run, build, test, lint, validate, generate, CI, and a discoverable help summary.",
"
Makefileandpackage.jsonexpose aligned behavior for the supported workflows so maintainers do not need to learn two different command vocabularies.","Specialized phase-specific verification commands remain available only as internal or advanced utilities and are no longer the primary commands a maintainer encounters first.",
"Build, validation, and test workflows reuse explicit generation prerequisites instead of depending on hidden manual sequencing by the developer.",
"Command-level verification proves the supported workflow works from a fresh local state and catches regressions when generation requirements change.",
"Quality gate: typecheck, lint, and the relevant automated tests pass."
],
"userStories": [
{
"id": "make-dev-utilities-001",
"title": "Restore a generated-content-aware local dev entrypoint",
"description": "As a developer running the docs site locally, I want
make devto prepare the generated artifacts the app now depends on so I can start the site from a normal checkout without memorizing extra setup commands.","acceptanceCriteria": [
"Running
make devfrom the repository root triggers the required generation and validation prerequisites for local development before the Next.js dev server starts.","The command works when generated page outputs are missing or stale; it regenerates what is needed instead of failing with missing-runtime-artifact errors.",
"The dev workflow avoids unnecessary production-only checks that would make normal local startup unexpectedly slow or brittle.",
"A maintainer-visible failure during preparation names the missing or invalid prerequisite and the command that can repair it.",
"Typecheck passes",
"Tests pass"
],
"priority": 1,
"passes": true,
"notes": ""
},
{
"id": "make-dev-utilities-002",
"title": "Provide one small supported command surface for common maintainer workflows",
"description": "As a developer new to the repository, I want a short list of top-level commands for the common workflows so I can immediately tell how to run, build, test, lint, validate, and regenerate the project.",
"acceptanceCriteria": [
"The default top-level workflow includes commands for
dev,build,test,lint,validate,generate,ci, andhelp.","
make helpor an equivalent top-level discoverability command prints a concise summary describing what each supported workflow command does.","The top-level command names describe maintainer goals rather than internal implementation phases.",
"The command surface does not require a maintainer to choose among many phase-specific test or convergence commands to do normal local work.",
"Typecheck passes",
"Tests pass"
],
"priority": 2,
"passes": true,
"notes": ""
},
{
"id": "make-dev-utilities-003",
"title": "Align Make and Bun workflows while demoting noisy internal commands",
"description": "As a maintainer switching between
makeandbun run, I want the same workflow names and behavior in both places so the tooling feels consistent and the advanced scripts do not crowd the default interface.","acceptanceCriteria": [
"Each supported top-level workflow has a matching Bun script and Make target with equivalent observable behavior.",
"Internal generators, narrow verifiers, and phase-specific checks are grouped behind a clearly advanced or internal namespace instead of appearing as the primary everyday workflow.",
"Existing CI or specialist workflows that depend on deeper verification can still invoke those internal commands without changing the user-facing default workflow.",
"Cleanup of
Makefileandpackage.jsonremoves redundant aliases and contradictory entrypoints rather than merely adding more wrappers.","Typecheck passes",
"Tests pass"
],
"priority": 3,
"passes": true,
"notes": ""
},
{
"id": "make-dev-utilities-004",
"title": "Add command-contract verification for the supported workflow",
"description": "As a maintainer, I want automated proof around the supported developer commands so future content-generation changes do not silently break local workflows again.",
"acceptanceCriteria": [
"Automated tests or command-contract checks cover the supported top-level workflows that changed in this work item, including at least
devpreparation,build,validate, and one aggregate quality command.","The checks assert observable outcomes such as successful exit status, expected prerequisite generation, or expected help output instead of asserting internal file inventories unless those files are part of the command contract.",
"A regression where generated page prerequisites are omitted from
devorbuildcauses automated failure.","The verification remains focused on the supported workflow surface and does not expand into unrelated command-cleanup assertions.",
"Typecheck passes",
"Tests pass"
],
"priority": 4,
"passes": true,
"notes": ""
}
]
}