One room.
A plan for booking it.

# Start here

**Editorially authored demonstration — community-room bookings.** These are guidance documents, not finished application code. Important booking rules remain open; do not build the reservation workflow from invented defaults.

1. Read README.md for the exact source idea and displayed clarification.
2. Read docs/01-PRODUCT-SCOPE.md and check the member and coordinator permissions.
3. Review docs/08-OPEN-DECISIONS.md. Resolve the booking rules and coordinator assignment before implementing the affected behaviour.
4. Open FILE-MAP.md and choose the starting prompt in prompts/ for your builder. Supply the referenced files manually.
5. Ask the builder to propose the first small step in docs/07-BUILD-PLAN.md, with a concrete check. Review the proposal before any implementation.

For this example, the first useful step is a decision worksheet, not a working booking app. Keep the folder together so relative references remain understandable.

# Community-room bookings

**Editorially authored demonstration.** This example shows the PenguinKit document format. It is not a customer project, an AI-generated kit, or evidence of a working application. Booking rules below still need decisions; this example is not ready for a complete implementation.

## Original idea

“Our neighbourhood group has one meeting room and people keep asking in the group chat when it’s free. I want a phone-friendly booking app for our members. Members should sign in, see the room’s availability and their own bookings, reserve an open time, and cancel their own reservation. A few coordinators should see all reservations, block unavailable times, and cancel any reservation when needed. The first version is just for our group and this one room; no payments, multiple locations, or public discovery. We still need to decide opening hours and time zone, booking length, how far ahead people can book, cancellation rules, cleanup time between bookings, and how to appoint the first coordinator.”

## One meaningful clarification

**Question:** When a member picks an available time, should the room be reserved right away, or should a coordinator approve each request first?

**Example answer:** Reserve it right away. Coordinators can block unavailable times and cancel a booking if plans change.

The answer makes immediate confirmation part of the example scope. An approval queue is outside this first version.

## How to read this example

Confirmed requirements come only from the displayed idea and answer. Architecture, data models and safeguards are suggestions. No technology stack has been accepted. Opening hours, time zone, booking duration, advance limit, cancellation rules, cleanup gaps and first-coordinator assignment remain open. Begin with START-HERE.md and docs/08-OPEN-DECISIONS.md. No application source code is included.

# File map

Editorial demonstration; no application source code is included.

- START-HERE.md — first session and unresolved-rule warning.
- README.md — exact public idea and clarification.
- AI-PROJECT-CONTEXT.md — short context and authoritative document references.
- AGENTS.md and CLAUDE.md — builder entry instructions.
- docs/01-PRODUCT-SCOPE.md
- docs/02-USER-FLOWS.md
- docs/03-ARCHITECTURE.md
- docs/04-DATA-AND-INTEGRATIONS.md
- docs/05-UI-AND-CODING.md
- docs/06-SECURITY-AND-TESTING.md
- docs/07-BUILD-PLAN.md
- docs/08-OPEN-DECISIONS.md

- prompts/START-WITH-CODEX.md
- prompts/START-WITH-CLAUDE-CODE.md
- prompts/START-WITH-CURSOR.md
- prompts/START-WITH-CHATGPT.md

# Community-room bookings — builder context

Editorially authored demonstration, not generated-product quality evidence. Build guidance only; booking-rule decisions remain unresolved.

The first version is one community room for one neighbourhood group. Members sign in, see shared availability and their own bookings, reserve an open time with immediate confirmation, and cancel their own reservations under a rule still to decide. Coordinators see all reservations, block unavailable times and cancel any reservation. No payments, multiple locations, public discovery or approval queue.

The exact idea and answer are in README.md. Detailed scope is authoritative in docs/01-PRODUCT-SCOPE.md; open rules are in docs/08-OPEN-DECISIONS.md. Do not invent values for opening hours, time zone, duration, advance limit, cancellation, cleanup gap or first-coordinator assignment. Member onboarding and block-versus-booking behaviour also need clarification. No technology stack has been accepted.

Use docs/03-ARCHITECTURE.md and docs/04-DATA-AND-INTEGRATIONS.md as recommendations. Begin with the decision worksheet in docs/07-BUILD-PLAN.md and propose a concrete check before implementing anything.

# Product scope

## Project description

Build a mobile-friendly booking app for one neighbourhood community room. Members should be able to sign in, view the room’s availability, make a reservation for an open time, and cancel their own reservation. A reservation is confirmed as soon as it is made. Members can see their own bookings and the shared availability calendar.

Coordinators should be able to block dates or times when the room is unavailable, view all reservations, and cancel a reservation when needed. The first version is for one room and one local group. It does not need payments, multiple locations, public discovery, or an approval queue.

## Source and boundaries

The original brief in README.md establishes one room, one group, mobile use, sign-in, member rights, coordinator rights and excluded features. The displayed answer establishes immediate confirmation. These are confirmed only within this authored example.

Do not add reminders, recurring reservations, waitlists, invitations, guest access, billing or public registration as confirmed requirements. Member onboarding and technology choices need review if they affect implementation.

## Decisions needed before build

Booking length, opening hours and time zone; how far ahead members can reserve; cancellation cutoff and the process after it; setup/cleanup gaps; and safe first-coordinator assignment remain unconfirmed. See docs/08-OPEN-DECISIONS.md. No values are supplied or implied.

## Suggested success check

Once the rules are agreed, demonstrate a member reserving an allowed open time, seeing the immediate confirmation, and cancelling their own reservation under the agreed rule. Show a coordinator blocking an unavailable time and managing reservations. Check that conflicting reservations cannot both succeed. This is a proposed acceptance check, not a test result.

# User flows

## Member journey

1. Sign in as a member of the group. The onboarding method remains to be agreed.
2. View shared availability for the one community room. Other members' identities and booking details are not part of the confirmed member scope.
3. Select a permitted available time using the booking rules still to be agreed.
4. Submit a reservation. If it succeeds, show immediate confirmation; there is no approval queue.
5. View own upcoming reservations. Request cancellation of an owned reservation under the cancellation rule that must be settled before this feature is implemented.

## Coordinator journey

1. Sign in with coordinator access assigned through an agreed safe process.
2. View all reservations and block unavailable periods.
3. Cancel any reservation when needed. Distinguish this permission from the member's own-reservation permission.

## Suggested failure handling

If another request took the time first, preserve the attempted selection, explain the conflict and refresh availability. If a save fails, do not display a confirmed reservation. Decide how a new block interacts with an existing booking; do not silently cancel or permit conflicts. Cancellation after the member cutoff needs an agreed recovery message and coordinator process.

# Suggested architecture

**Recommendation, not an accepted technology stack.** A small web application with a phone-friendly calendar, authenticated server operations and a relational store is a plausible starting point. Discuss the group's existing tools and maintenance capacity before accepting technologies.

The browser displays availability and the member's own bookings. The server validates identity, role, ownership, agreed booking rules and availability when saving. Coordinators use the same application with additional authorised actions. Server rules remain authoritative even if the interface hides an action.

## Proposed application structure

- app/ — calendar, own bookings and coordinator screens.
- booking/ — reservation commands and agreed booking-rule checks.
- access/ — authenticated member/coordinator permission checks.
- data/ — reservation and unavailable-period storage.
- tests/ — permissions, booking rules and overlapping request checks.

These folders are a documentation proposal; this archive contains no working scaffold.

## Tradeoff

A database-enforced conflict constraint can protect overlapping writes more reliably than a browser-only check. It adds data modelling and transaction work. Consider the actual datastore before choosing a mechanism; a displayed calendar alone cannot prevent concurrent conflicts.

No payment gateway, public directory, multiple-location service or approval queue is needed for the confirmed scope. Decisions in docs/08-OPEN-DECISIONS.md must be settled before finalising reservation logic.

# Suggested data and integrations

**Proposed model — review before implementation.** Keep room configuration separate from reservations so the agreed rules can be changed deliberately.

- Member identity and coordinator role: use the accepted authentication approach. A user must not grant themselves coordinator access.
- Reservation: identifier, member reference, start/end instants and cancellation state. Retain only information the group needs.
- Unavailable period: start/end and an optional coordinator-facing reason. Decide how blocks interact with existing reservations before implementing them.
- Room rules: opening hours, time zone, permitted duration, advance limit, cancellation rule and any setup/cleanup gap. All values remain decisions needed.

## Time handling recommendation

Store reservation instants consistently and display them in the room's agreed time zone. Define how daylight-saving changes and ambiguous local times behave if the selected zone has them. Do not invent a time zone or default operating hours. Validate start before end and include the agreed cleanup gap in conflict checks where applicable.

## Integrations

Authentication is required by the brief, but the provider and member onboarding method have not been accepted. No billing, external calendar sync, messaging integration or email reminder is a confirmed feature. Avoid adding them to the first version without a new explicit scope decision.

# Suggested UI and coding guidance

Use a calm mobile-first calendar with an obvious selected time and one primary reservation action. Show availability with text or symbols as well as colour. A separate own-bookings view should make upcoming bookings and eligible cancellation actions easy to find.

Coordinator controls should make their broader permissions clear. Before a coordinator cancels a reservation, show which booking is affected. Never show another member's private booking details in the member calendar without an explicit decision to do so.

## Suggested implementation habits

- Keep booking rules in one validated configuration source after the group agrees them.
- Enforce role, ownership and conflict checks on the server; visible controls are a convenience, not permission enforcement.
- Preserve input on failed saves and distinguish saving, confirmed and failed states.
- Keep date/time formatting separate from reservation validation.
- Use labelled fields, visible keyboard focus and clear error messages. Review the calendar and cancellation flow on a narrow phone screen.

No component library or visual theme is accepted for this example. These recommendations support the brief without adding features. Booking duration, opening hours and cancellation behaviour must remain visibly undecided until agreed.

# Suggested security and testing checks

These are proposed checks, not completed tests or proof of security.

## Access

Unauthenticated visitors cannot create or cancel reservations. Members can see and cancel only their own reservations under the agreed rule. Coordinators can view all reservations, block periods and cancel any reservation. Test server requests directly as well as visible controls. A member must not be able to promote their role by changing browser data.

## Availability

Submit two overlapping reservation requests together and verify that at most one succeeds. Test reservations against blocked periods and any agreed cleanup gap. Confirm the selected conflict mechanism protects writes atomically. Determine block-versus-existing-booking behaviour first.

## Rules

After decisions are recorded, test opening-hour boundaries, duration, advance window, member cancellation cutoff and the process after cutoff. Include time-zone changes and ambiguous local times where applicable. Do not substitute guessed values for these tests.

## Usability and recovery

Review sign-in, availability, selected time, confirmation, own bookings and cancellation at a narrow phone width and with keyboard navigation. A failed save must not look confirmed. A conflict message should explain the next step. Use invented demonstration identities in development, not actual group members' data.

# Suggested build plan

**Editorially authored demonstration.** The first step resolves unknowns; the following implementation steps are conditional on those decisions. No completed build or test result is claimed.

## Step 1 — Agree the booking rules

Confirm opening hours and time zone, booking duration, advance-booking limit, cancellation cutoff, and any gap needed between reservations. Keep these values in one place so the group can adjust them without changing the booking flow.

**First small task:** create a decision worksheet using docs/08-OPEN-DECISIONS.md. Ask the group to supply each value, including the post-cutoff cancellation process and safe first-coordinator assignment. Also settle how blocks interact with existing reservations and how members join. Do not implement booking mutations yet.

**Check:** every unresolved rule has either an explicitly accepted answer or a named affected feature that remains blocked. Do not claim Step 1 is complete while the reservation rules remain open.

## Step 2 — Define who can do what

A signed-in member can view availability, create a reservation in an open slot, view their own reservations, and cancel their own reservation under the cancellation rule settled in Step 1. A coordinator can view all reservations, block an unavailable period, and cancel any reservation. Proposed implementation check: enforce these permissions on the server as well as in the visible interface.

**Check:** using demonstration accounts, member requests to access or cancel another member's booking fail; authorised coordinator requests succeed. Role assignment follows the accepted safe process.

## Step 3 — Prevent overlapping reservations

Check availability when the server saves a reservation, not only when the calendar is displayed. Store each reservation’s start and end time consistently. Reject a conflicting request with a clear message and refresh the available times.

**Check:** two overlapping simultaneous requests cannot both succeed. Test blocked periods, boundary times and any accepted cleanup gap.

## Step 4 — Build and review the member journey

Show the calendar, selected time, confirmation, upcoming bookings, and cancellation action on a narrow phone screen. Make unavailable and already-booked times understandable without relying on colour alone.

**Check:** complete a reservation and eligible cancellation using keyboard navigation and on a phone-width screen. Failed saves preserve the selection and never show false confirmation.

## Step 5 — Check the important cases

Confirm that two overlapping requests cannot both succeed; members cannot edit another member’s booking; coordinators can manage availability; and cancellation follows the agreed rule. Review the flow on a phone before extending the scope.

**Check:** record actual results for the cases in docs/06-SECURITY-AND-TESTING.md. Keep payments, multiple locations, public discovery and an approval queue outside this version.

# Decisions needed

**Unresolved in this editorial example.** None of the values or mechanisms below has been supplied or accepted. Resolve the affected rules before implementing the complete reservation flow.

1. Opening hours and room time zone — define bookable times and how local times are interpreted.
2. Booking duration — fixed slots or allowed variable lengths, including any minimum/maximum.
3. Advance-booking limit — how far ahead a reservation can be made.
4. Member cancellation — cutoff, when it is measured, and what the member does after it. Coordinator cancellation remains permitted by the brief.
5. Setup/cleanup gap — whether time between bookings is required and how it affects availability.
6. First coordinator — a safe way to assign the first privileged account; users must not promote themselves.

## Further implementation clarifications

The brief does not define member onboarding or how a new unavailable period should interact with an existing reservation. Clarify these before implementing the affected operations. The technology stack and authentication provider are recommendations to discuss, not accepted choices.

## Already settled in the example

One room, one neighbourhood group, mobile-friendly use, member sign-in, shared availability, own bookings and cancellation, coordinator access to all reservations and unavailable periods, immediate confirmation, no payments, no multiple locations, no public discovery and no approval queue. Trace these to README.md rather than treating them as new open questions.

# Builder instructions

This is an editorial demonstration with unresolved rules, not a completed application. Read START-HERE.md and FILE-MAP.md. Use docs/01-PRODUCT-SCOPE.md for confirmed example scope and docs/08-OPEN-DECISIONS.md for unknowns. Treat architecture and implementation safeguards as suggestions until accepted.

Follow docs/07-BUILD-PLAN.md one small step at a time. Ask before choosing any unresolved consequential rule. Preserve one room, one group, immediate confirmation and member/coordinator permissions. Do not add payments, public discovery, multiple locations or an approval queue. Review security and data guidance before writing access or reservation operations. Never claim this example has passed implementation tests.

# Claude Code instructions

Follow AGENTS.md and START-HERE.md. Read the documents needed for the current step from FILE-MAP.md. Summarise confirmed scope, suggested implementation and decisions needed separately. Propose the first small step and its check; wait for the user's approval before editing. Do not invent booking rules or present the proposed source tree as delivered code.

# Start with Chatgpt

Supply these files manually in your preferred tool or share them with your developer. No automatic import is provided.

> Read START-HERE.md, AGENTS.md, docs/01-PRODUCT-SCOPE.md, docs/07-BUILD-PLAN.md and docs/08-OPEN-DECISIONS.md. Summarise the confirmed requirements, suggestions and decisions needed separately. This is an editorial example with unresolved booking rules. Do not edit files yet or invent rule values. Propose the first small step, the files to create or change, and a concrete check. Wait for my approval before implementing.

# Start with Claude Code

Supply these files manually in your preferred tool or share them with your developer. No automatic import is provided.

> Read START-HERE.md, AGENTS.md, docs/01-PRODUCT-SCOPE.md, docs/07-BUILD-PLAN.md and docs/08-OPEN-DECISIONS.md. Summarise the confirmed requirements, suggestions and decisions needed separately. This is an editorial example with unresolved booking rules. Do not edit files yet or invent rule values. Propose the first small step, the files to create or change, and a concrete check. Wait for my approval before implementing.

# Start with Codex

Supply these files manually in your preferred tool or share them with your developer. No automatic import is provided.

> Read START-HERE.md, AGENTS.md, docs/01-PRODUCT-SCOPE.md, docs/07-BUILD-PLAN.md and docs/08-OPEN-DECISIONS.md. Summarise the confirmed requirements, suggestions and decisions needed separately. This is an editorial example with unresolved booking rules. Do not edit files yet or invent rule values. Propose the first small step, the files to create or change, and a concrete check. Wait for my approval before implementing.

# Start with Cursor

Supply these files manually in your preferred tool or share them with your developer. No automatic import is provided.

> Read START-HERE.md, AGENTS.md, docs/01-PRODUCT-SCOPE.md, docs/07-BUILD-PLAN.md and docs/08-OPEN-DECISIONS.md. Summarise the confirmed requirements, suggestions and decisions needed separately. This is an editorial example with unresolved booking rules. Do not edit files yet or invent rule values. Propose the first small step, the files to create or change, and a concrete check. Wait for my approval before implementing.