Reference Project: Internal Service Requests

This reference project is fictional. It demonstrates the SHAPE Framework using an internal application for submitting and reviewing service requests. The scenario is intentionally small enough that the relationship between business intent, specifications, implementation, and verification remains visible.

The example does not prescribe an enterprise technology stack, UI design, database architecture, or deployment model. Real projects must follow their own approved standards.

Employees currently submit internal service requests through inconsistent messages. The receiving team struggles to determine who owns a request, whether information is complete, and whether a decision has been communicated. The organization wants a basic workflow in which requests can be submitted and explicitly approved or rejected by authorized reviewers.

The first release should make the state of a request understandable to its requester and to the assigned reviewer. It does not attempt to automate fulfillment, service-level agreements, procurement, or production notification infrastructure.

Objective: Provide one traceable path for submitting and deciding internal service requests.

Intended users: Employees as requesters; designated staff as reviewers; an administrative role responsible for maintaining reviewer assignments if applicable.

In scope: Create and submit requests, validate required information, show request status, review submitted requests, approve or reject with recorded decisions, restrict actions according to roles, and allow a requester to inspect the result.

Out of scope: Fulfillment of approved requests, financial commitments, automated assignment optimization, external customer access, analytics dashboards, and production release procedures.

Initial business states: Draft, Submitted, Approved, Rejected. The meanings and allowed transitions are maintained in the feature specification.

The Product Engineer interviews several requesters and reviewers. Requesters want acknowledgment that a submission exists and a clear outcome. Reviewers need complete information and a reliable decision record. The Product Engineer identifies unresolved questions: Who can review requests? Can reviewers decide their own submissions? Is a rejection reason mandatory? Who may edit a submitted request?

The business owner confirms the first-release decisions: reviewers are assigned by an approved role; requesters cannot review their own submissions; a rejection requires a reason; and submitted requests cannot be edited in this first release. These decisions become specification content rather than discretionary assumptions made by the coding agent.

UX direction: The designer defines the main user journeys: create and submit a request; inspect its status; review and decide a submitted request. The designer relies on approved interaction patterns and plans to inspect the working flows later.

Technical foundation: The architect evaluates the organization's approved platform, starter repositories, libraries, components, and permissions model. The architect defines boundaries, data flows, integrations, separation of concerns, and repository structure, and coordinates enforced agent execution restrictions with environment owners. Project-specific guidance is available through agent_instructions/ and a minimal root AGENTS.md.

Specification work: The Product Engineer produces the following illustrative feature specification.

ID: SPEC-001
Title: Submit and review an internal service request
Purpose: Let an employee submit a service request and receive a traceable decision from an authorized reviewer.

Actors: Requester; Reviewer.

Behavior:

1. A requester may create a Draft request with a title, category, and description.
2. A request may move from Draft to Submitted only when all three fields are present and valid under the agreed field rules.
3. The requester can view the current status of requests they created.
4. A reviewer may view Submitted requests assigned to their review scope.
5. An authorized reviewer may approve a Submitted request, recording the reviewer's identity and decision time.
6. An authorized reviewer may reject a Submitted request only after providing a nonempty rejection reason; the result records the reviewer and decision time.
7. Requesters cannot approve or reject their own submissions, even if they otherwise possess reviewer permissions.
8. Once a request is Submitted, it cannot be edited in the initial release.
9. A requester can view the decision and rejection reason, where applicable, for their own request.

Acceptance conditions:

• AC-01 A Draft request cannot be submitted with a missing title, category, or description.
• AC-02 Successful submission changes the request to Submitted and makes its status visible to the requester.
• AC-03 Only an authorized reviewer may approve or reject an assigned Submitted request.
• AC-04 A reviewer cannot approve or reject their own request.
• AC-05 Rejecting without a reason is prevented; a valid rejection records its reason, reviewer, and decision time.
• AC-06 A Submitted request cannot be edited.
• AC-07 A requester may see the decision on their own request but not another requester's private details unless separately authorized.

Dependencies and unresolved questions: Reviewer assignment policy is defined by the organization's access model. Any notification beyond viewing request status is out of scope for the initial release.

This excerpt establishes observable behavior, but a real project must also define any necessary field constraints, data handling policies, and integrations under its approved architecture.

During parallel foundation work, the architect reviews the emerging requirements for consequential technical implications, chooses from enterprise-approved assets, clarifies system boundaries, and coordinates appropriate execution permissions with the relevant owners. The Product Engineer maintains the initial feature specifications and ensures the coding agent can discover project instructions. The UX designer establishes the essential interaction direction.

These activities produce enough shared context and technical preparation to begin meaningful implementation. Material exceptions follow existing enterprise policies. The SHAPE Framework does not require an additional formal Architecture Readiness Review before Stage 3; the architect's two planned reviews of implemented software occur at Stages 4 and 7.

The Product Engineer asks the coding agent to implement SPEC-001 using the approved project instructions, libraries, and patterns. The Product Engineer exercises representative Draft creation, submission, and normal approval and rejection workflows, confirms that the core flow is functioning, and identifies routine corrections for the agent to make.

The initial implementation appears ready for architect review, but the Product Engineer has not exercised rejection with an empty reason. That negative path remains defective: the application still permits a reviewer to reject a request without providing a reason, contrary to AC-05. The oversight is not treated as acceptable behavior or used to change the specification.

The architect checks the implementation before extensive stakeholder review. The review identifies a material issue: reviewer authorization is checked only in the user interface. This is insufficient because hiding a control does not enforce permissions on the underlying action. The Product Engineer directs correction using the enterprise's approved authorization approach. The architect confirms that the relevant action is protected before the client review proceeds.

Requesters and reviewers exercise the main workflows. A reviewer asks to add a comment when approving a request. The business owner decides that approval comments are useful but optional. The Product Engineer updates SPEC-001 and its acceptance conditions, then directs the coding agent to implement the agreed change. The updated specification, not the demonstration discussion alone, becomes the durable record.

A separate verification agent or context reads the current committed specification, including the acceptance conditions added or refined during stakeholder review. It independently derives representative positive and negative checks and exercises the available application behavior. Because the tests are grounded in the specification rather than the implementation agent's earlier choices, the verifier exercises the empty-rejection-reason case that was missed during the Product Engineer's initial checks.

The result includes the following illustrative outcomes:

The Product Engineer assigns the AC-05 failure to the implementation agent, confirms that the requirement has not changed, and directs a correction. The independent verifier repeats the empty-reason check and confirms that rejection is now prevented without a reason, while valid rejection still succeeds and records the expected details.

The blocked AC-07 privacy check is not counted as a pass. Before reporting verification complete, the team either supplies suitable test identities and reruns it or explicitly records an unresolved limitation for disposition under the organization's acceptance and risk policies. The example should not state that all checks passed when one remains blocked.

The architect reviews the revised implementation, confirms resolution of the authorization finding from Stage 4, considers the independent verification report, and evaluates any technical implications of the new optional approval comment. The architect records technical readiness for UAT, subject to the organization's normal policies.

The review also acknowledges the corrected and independently retested AC-05 rejection-reason finding. UAT receives a report distinguishing resolved failures from any outstanding AC-07 privacy-check limitation.

Business stakeholders test the submission and review workflows and make the acceptance decision under the organization's normal UAT procedure. Any new defects or agreed changes return to the specification and implementation loop. This example ends at UAT; the enterprise's release and operating processes are not covered by the SHAPE development cycle.

After the product is in use, stakeholders request that a requester be able to withdraw a Submitted request before a reviewer decides it. The Product Engineer adds the following agreed behavior to the specification corpus:

Change: A requester may withdraw their own Submitted request. Withdrawal changes the request state to Withdrawn, records who withdrew it and when, and prevents subsequent approval or rejection. Reviewers cannot withdraw on behalf of requesters unless a separate authorization decision is explicitly made.

The agent implements the enhancement within existing project standards. Independent testing checks authorized withdrawal, denial of withdrawal for other users, and rejection of a late review decision on a withdrawn request. The architect reviews the change if its security and workflow impact meets the organization's thresholds. Business stakeholders then conduct UAT. The Product Engineer retains responsibility for maintaining the feature and related specifications.

The project illustrates the SHAPE distinction between conversational discovery and maintained specifications; between a working interface and enforced permissions; between the coding agent's implementation and independent verification; between architect sign-off and business acceptance; and between a first product cycle and later enhancement work.

It also shows why durable specifications matter after release: the withdrawal enhancement must account for the behavior and state transitions already established in the original product.