Agentic Development Workflow: Why Specs May Matter More Than More Agents

An agentic development workflow promises to turn plain-language requests into working software, but the hard part is rarely getting an AI to write a first draft of code. The harder problem is keeping intent, scope, and technical decisions intact after the agent’s context window closes, the task expands, and another developer—or another agent—takes over.

That is the central idea behind Frame, an open-source project shared by its creator in r/SaaS after roughly eight months of work. Rather than positioning itself as another autonomous coding agent, Frame treats the repository as a durable memory layer: an agent turns an initial request into a written specification, resolves open questions before planning, records the eventual outcome, and checks whether the documentation still matches the codebase. The project’s premise is simple: better analysis and a better plan should produce better implementation results.

The interesting question is not whether teams need more AI coding tools. They plainly have plenty. The question raised by Frame—and by the skeptical response in the Reddit thread—is whether a dedicated workflow product is meaningfully better than a set of agent skills, Markdown files, templates, and a searchable documentation site. The answer depends on whether the tool can enforce a reliable lifecycle rather than merely generate more documents.

What Frame is trying to solve

The original Frame announcement describes a familiar failure mode in AI-assisted development. A developer opens a new coding session, gives an agent a task, receives a workable implementation, and then discovers that the reasoning behind crucial choices exists only in a vanished chat transcript. On the next session, someone has to explain the application again, re-establish constraints, and hope the model does not touch an unrelated area of the repository.

Frame’s proposed answer is a chain of repository-committed Markdown artifacts:

1. A request begins as a plain-language description of work.
2. An agent turns that request into a spec covering the problem, goal, constraints, success criteria, and exclusions.
3. Before the agent creates an implementation plan, it asks clarification questions about decisions the spec leaves unresolved.
4. After implementation, it creates an outcome record describing the original plan, what actually happened, and what was changed or reversed.
5. The project can run a freshness check to flag drift between written context and the repository.

That is a significant distinction from a typical prompt file. The ambition is not simply “put instructions in a Markdown file.” It is to make the Markdown file an artifact with a purpose, lifecycle, relationship to prior decisions, and a defined point at which it should be revisited.

Frame’s creator says new specifications can identify which earlier decision they supersede. That creates a decision history rather than a pile of stale notes. In principle, an agent entering a mature codebase could read the current decision record, understand why an earlier approach was rejected, and avoid confidently reintroducing it.

The source project is available as an open-source GitHub repository, while the public launch post asks developers to pressure-test the idea with feedback. The creator frames it as a lesson learned while trying to productize a personal “software factory” workflow: building a serious product around agentic development takes much longer than assembling a private stack of scripts and prompts. (reddit.com)

Why an agentic development workflow needs durable context

LLMs can summarize code, write tests, refactor components, and execute multi-step plans. But they do not automatically inherit reliable institutional memory. Even when an agent has broad repository access, code alone often cannot answer the questions that determine whether a change is correct.

Consider a seemingly routine request: “Add company-wide SSO.” The code may reveal the existing authentication provider and user schema. It may not reveal whether enterprise SSO is intentionally limited to a higher plan, whether support has committed to a migration path for existing accounts, whether SCIM provisioning is excluded from the first release, or whether legal requires a particular audit event before rollout.

Those decisions are product and operational context. They need to survive beyond an individual model run.

Code explains implementation, not necessarily intent

A diff tells reviewers what changed. A test tells them which behavior is expected. Neither necessarily explains why the team chose a particular trade-off. That missing rationale becomes expensive when a future developer sees apparently redundant logic and removes it, or when an AI agent optimizes for local elegance while breaking a historical constraint.

This is why durable written context matters most for changes that have one or more of these properties:

• They cross multiple services, packages, or repositories.
• They alter customer-facing behavior or business rules.
• They affect security, permissions, payments, data retention, or compliance.
• They replace a prior decision rather than introduce an isolated feature.
• They require staged rollout, migration, rollback, or operational monitoring.

For a tiny UI copy edit, a full specification workflow would be overhead. For a multi-week authorization redesign, relying only on chat history is fragile.

The hidden cost is repeated re-explanation

Many teams measure AI coding productivity in generated lines, tasks closed, or time to first prototype. Those metrics miss the cost of repeatedly reconstructing the same context. A developer may spend 15 minutes orienting an agent at the beginning of each session, then spend another 30 minutes correcting assumptions that a written constraint could have prevented.

A repository-native spec turns that repeated conversation into a shared asset. It gives a coding agent a starting point, gives human reviewers a way to challenge the framing before implementation, and gives future maintainers a compact account of the trade-offs behind a change.

GitHub’s own collaboration model already recognizes that a pull request needs more than a code diff: it combines a description and discussion with commits, checks, changed files, and review state. Frame’s approach can be seen as extending that context upstream, before the first implementation branch is created. (docs.github.com)

Frame’s core model: spec, plan, outcome, freshness

The project’s workflow is best understood as four layers of control rather than a single autonomous agent.

1. The spec establishes the problem boundary

The spec is where an ambiguous request becomes a testable statement of work. A useful spec answers five questions:

The “out of scope” section deserves special attention. AI agents are good at noticing adjacent improvements. That can be helpful in a prototype, but it becomes dangerous when an agent turns a focused bug fix into a cleanup of shared abstractions, test suites, dependencies, and API contracts. A written boundary lets the developer say no before the extra work becomes part of the diff.

2. Clarification happens before the plan

The second layer is a deliberate pause. If the request has unresolved choices, the agent should ask questions before committing to a plan.

This is one of the strongest elements of the idea. Coding agents are often rewarded for momentum, so they may infer unstated requirements and start editing. The result can be technically competent but product-wrong work. A clarification stage changes the agent’s job from “guess and proceed” to “surface ambiguity and obtain a decision.”

For example, a request to “notify users when a report is ready” leaves open several choices: email, in-app notification, webhook, or all three; instant delivery or digest; owner-only or collaborators; retries; localization; unsubscribe behavior; and whether the notification is part of the initial release. A plan that skips these questions may look decisive, but it is simply making product decisions without authorization.

3. The outcome file captures reality, not just intent

Plans are not contracts with reality. A migration may uncover malformed historical records. An API may lack a needed endpoint. A performance test may invalidate the initial design. A security review may force a different approach.

That is why outcome records are more valuable than static design docs. They describe not only what was intended but also what changed, why it changed, and what was abandoned. In effect, they provide a compact audit trail for a unit of work.

A strong outcome file could include:

• Links to the original spec and pull request.
• The final implementation summary.
• Deviations from the plan and the reason for each one.
• Explicit reversals of earlier decisions.
• Tests run, rollout conditions, and known follow-up work.
• Any documentation that needs another owner or review date.

This does not replace issues, pull requests, or architecture decision records. It connects them into a repeatable story that agents can read without trawling through months of tickets and chat messages.

4. Freshness checks recognize that documentation decays

The hardest feature to implement well may be Frame’s stated freshness check. Documentation drift is not just a writing problem; it is a systems problem. A useful check needs to understand enough about the codebase and artifact relationships to detect when a material assumption has become invalid.

A weak version merely compares file timestamps. A better version checks whether referenced files, endpoints, configuration keys, data models, or commands still exist. A stronger version could inspect pull requests and flag specs whose stated scope conflicts with files actually changed. The most useful result is not “documentation is stale”; it is a specific warning such as: “This outcome says billing is handled only by invoice.created, but the referenced event handler was removed in commit X.”

The Reddit critique is the right product question

The most useful top comment on the launch post asks why a developer could not create a skill that follows the same spec flow, pair it with implementation-agent instructions, store everything in Markdown, and serve it through a searchable interface. That is not a dismissal. It is the exact question every workflow product must answer.

At a basic level, the commenter is correct. The ingredients are already available:

• Agent instruction files or reusable skills.
• Markdown for durable, version-controlled writing.
• Git for history and review.
• Static documentation tooling for search and navigation.
• Pull request templates, issue templates, and CI checks.

GitHub itself supports Markdown files in repositories, generates a table of contents from headings, and supports templates that pre-fill information in pull request bodies. Those native building blocks can cover much of a lightweight spec-driven workflow without another application. (docs.github.com)

So where could Frame be genuinely superior?

It must offer conventions, not just generated files

A generic skill can tell an agent to create spec.md. But a focused workflow tool can impose a stable schema, folder structure, naming convention, state transitions, cross-links, and supersession rules. Consistency becomes valuable as the number of decisions grows.

A spec that every agent writes differently is hard to search, compare, and validate. A standard artifact model makes it possible to ask questions such as: Which completed specs lack outcome records? Which active specs touch authentication? Which decisions were superseded in the past quarter? Which documents refer to deleted modules?

It must reduce user effort at the moment of work

The product should make the right behavior easier than the shortcut. If developers have to remember a command, choose the correct template, find prior documents, manually insert links, and update status fields, the workflow will degrade under deadline pressure.

The real product value is orchestration: collect context, identify ambiguity, propose the artifact, connect it to previous work, and make the next correct action obvious. If Frame automates those steps reliably, it is more than a prompt pack.

It must make quality observable

The strongest argument for a dedicated tool is measurement. A system can track whether work began with a spec, whether open questions were resolved, whether a plan exceeded declared scope, whether an outcome was written, and whether the artifacts remain fresh.

Without those signals, “we use specs” can turn into a ceremonial claim. The files exist, but nobody reads them, updates them, or verifies whether they still describe the system.

Skills, templates, and docs sites: practical alternatives

Frame is not the only sensible implementation of this philosophy. Teams should choose the lowest-complexity approach that solves their actual coordination problem.

Option A: Agent skills plus repository conventions

For a small team, the leanest option is to create a reusable agent skill or instruction set that requires a spec before non-trivial work. Store specs under a predictable directory such as docs/specs/, and add an outcomes/ directory for completion records.

This works when the team already has disciplined engineering habits, the repository is not enormous, and someone is willing to maintain the conventions. It is inexpensive and portable across agent vendors.

Its weakness is enforcement. The process depends on people and agents following a prompt. There may be no central record of skipped steps, stale references, or superseded decisions.

Option B: Pull request and issue templates

A pragmatic middle ground is to place problem statements, scope, test criteria, and rollout notes directly in issue and pull request templates. GitHub supports templates that automatically appear in the pull request body, which can make basic context capture nearly frictionless. (docs.github.com)

This option fits teams whose work already flows through issues and PRs. It keeps discussion close to review, supports approvals, and benefits from existing automation.

The limitation is longevity. Pull request conversations can become noisy and difficult for an agent to treat as authoritative context. They are also less suited to maintaining an evolving sequence of architecture or product decisions across multiple changes.

Option C: Architecture decision records and a docs portal

Architecture decision records, product requirement documents, and a static docs site are a strong answer for teams that need readable, durable governance. Markdown remains version-controlled, documentation can be indexed, and humans can browse the decision history outside the code editor.

This is especially attractive where non-engineering stakeholders need access. Product managers, security reviewers, and support leads may prefer a well-organized site to a repository tree.

The challenge is synchronization. Unless the process is tied directly to implementation, docs can become an archive of good intentions. Frame’s freshness concept is aimed directly at this weakness.

Option D: A purpose-built agentic development workflow

A dedicated tool earns its place when the team needs predictable artifacts, agent-aware context assembly, explicit decision supersession, automated freshness checks, and reporting around process adherence.

That is the territory Frame is trying to occupy. It should not be judged by whether Markdown is novel. It should be judged by whether it turns Markdown, agent behavior, and repository history into a low-friction system of record.

How to test Frame without overhauling your process

The wrong way to evaluate a workflow tool is to deploy it across every repository immediately. The right way is to select a change that is large enough to expose coordination problems but contained enough to review in a few weeks.

A good pilot might be a new integration, permission model change, billing flow, data import, or API versioning project. Avoid a trivial change, because it will make any process look bureaucratic. Avoid a company-wide rewrite, because too many variables will obscure whether the workflow helped.

A 30-day evaluation plan

1. Pick one meaningful feature. It should involve at least two contributors or multiple agent sessions.
2. Write a baseline. Record how long the team normally spends on clarification, implementation, review revisions, and documentation updates.
3. Require a spec before code changes. Include the problem, constraints, success criteria, exclusions, and unanswered questions.
4. Review the plan separately from the code. This is where product owners and technical leads can correct direction cheaply.
5. Track scope deviations. Note every file or behavior change that was not in the original plan, then classify it as necessary, useful-but-deferred, or accidental.
6. Create an outcome file. Capture surprises, reversals, testing evidence, and follow-ups before the task is declared complete.
7. Revisit the work after two weeks. Ask a developer who did not implement it to explain why key choices were made using only the repository artifacts.

The final test is not whether the agent produced polished documentation. It is whether a new contributor can accurately continue the work without reopening the original chat session.

Metrics worth watching

Avoid vanity metrics like number of specs created. Instead, measure outcomes:

• Time from request to approved implementation plan.
• Number of material clarifications found after coding began.
• Number of review cycles caused by scope or requirement misunderstandings.
• Percentage of completed changes with explicit outcome records.
• Percentage of specs with broken links or obsolete references after 30 days.
• Time required for a new developer or agent to become productive on a related task.

If the workflow adds writing but does not reduce rework, review friction, or onboarding time, it is ceremony. If it prevents even one expensive mis-scoped change, it may be worthwhile.

Where this approach can fail

The Frame model has real risks, and acknowledging them is essential.

First, AI-generated specs can create an illusion of rigor. A document with headings and bullet points is not automatically a good specification. If the agent invents requirements, hides uncertainty, or writes vague success criteria, the team has merely moved hallucination earlier in the development lifecycle.

Second, too much process can slow the smallest tasks. Teams need a clear threshold: perhaps no spec for copy changes, one-file bug fixes, or mechanical dependency updates; lightweight specs for contained features; and full spec-plan-outcome records for cross-cutting or high-risk work.

Third, a stale spec can be worse than no spec if agents treat it as ground truth. Freshness checks need to be actionable, explain their evidence, and allow an explicit “still valid” confirmation. Otherwise, developers will learn to ignore warnings.

Fourth, sensitive decision records must be handled carefully. Putting product strategy, security trade-offs, customer information, or incident analysis into a repository can expand the audience for information that should remain restricted. Repository permissions, secret scanning, document redaction, and separate private records may be necessary.

Finally, tool lock-in is a concern. The best version of this idea keeps the durable assets in ordinary, readable Markdown. That way, even if the orchestration layer changes, the organization retains its decision history and can migrate to a different tool or agent.

The broader trend: agent development is moving upstream

Frame arrives as the AI tooling ecosystem shifts from “can an agent write code?” toward “can teams safely and repeatably build with agents?” Orchestration frameworks help coordinate multiple agents, while governance and testing tools are increasingly aimed at making agent behavior inspectable, constrained, and testable.

Microsoft’s open-source Conductor, for example, emphasizes deterministic routing in multi-agent workflows defined in YAML rather than letting every next step be decided by a model. That reflects a broader engineering preference: use model judgment where it is useful, but make repeatability and control explicit where the workflow is known. (opensource.microsoft.com)

Microsoft has also released RAMPART and Clarity for agent-development safety. RAMPART is positioned around repeatable adversarial and benign testing in CI, while Clarity is designed to help teams interrogate whether they are building the right thing before implementation starts. The overlap with Frame is notable: both treat early-stage problem framing as an engineering control, not a paperwork exercise. (microsoft.com)

These projects are not direct substitutes. Frame focuses on the software change lifecycle and repository memory; RAMPART focuses on safety testing; deterministic orchestration tools focus on agent routing. But together they show where the market is heading: away from one-shot prompts and toward structured systems that make agent work reviewable, repeatable, and recoverable.

What founders and engineering leaders should take from Frame

For founders, the biggest lesson is product scope. A private agent workflow can feel magical because its creator knows every unwritten assumption. Turning it into a product means solving onboarding, defaults, integrations, artifact design, failure handling, and the “why not just use a prompt?” question for strangers.

For engineering leaders, the takeaway is more operational. AI coding tools multiply implementation capacity, but they also multiply the number of changes that can be initiated without shared understanding. That makes written scope, decision history, and review gates more—not less—important.

For developers, the practical lesson is to preserve reasoning close to code. You do not need to adopt Frame to start. A simple docs/decisions/ folder, a lightweight spec template, and a completion note for significant work can already make agent sessions more coherent and future maintenance less mysterious.

The best agentic development workflow will not eliminate judgment. It will make judgment visible at the moment it is cheapest to challenge, preserve it after the chat window disappears, and connect it to the code that ultimately ships.

Conclusion

Frame’s most compelling idea is not autonomous implementation. It is the claim that AI-assisted development needs a durable memory system for intent, scope, and changed decisions.

The Reddit commenter asking for a comparison with skills, Markdown, and searchable documentation is right to demand a sharper answer. A separate tool is only justified if it makes specs easier to create, decisions easier to trace, process gaps easier to detect, and repository context more reliable for both humans and agents.

If Frame can do that, it becomes more than another layer in the AI coding stack. It becomes a structured operating system for the work that happens before, during, and after an agent writes code. If it cannot, a well-designed set of repository conventions may be the better choice. Either way, the underlying principle is sound: when agents accelerate execution, teams need stronger mechanisms for remembering why they chose a direction in the first place.

FAQ

What is an agentic development workflow?

An agentic development workflow is a structured process in which AI agents help move software work from a request through clarification, planning, implementation, review, and documentation. The best workflows preserve the relevant context and decisions in durable artifacts instead of leaving them only in chat history.

How does Frame differ from a coding agent?

A coding agent primarily generates or modifies code. Frame is designed around the surrounding workflow: turning requests into specs, resolving ambiguity before planning, recording implementation outcomes, maintaining decision history, and detecting documentation drift.

Can a team build this workflow with Markdown and prompts alone?

Yes. Small, disciplined teams can use agent skills, Markdown templates, pull request templates, and a documentation site to implement much of the same approach. A dedicated tool becomes more attractive when teams need consistent structure, automated context retrieval, decision supersession, freshness checks, and workflow reporting.

When should teams require a written spec before AI coding begins?

Require one for changes that are cross-functional, security-sensitive, customer-facing, difficult to reverse, or likely to span multiple coding sessions. Skip or simplify the process for small, isolated, low-risk maintenance tasks.

What makes a specification useful for an AI agent?

A useful spec states the problem, desired outcome, constraints, success criteria, explicit exclusions, and unresolved questions. It should also link to relevant existing decisions and identify what evidence will show the change is complete.