---
name: hasanat-builder
description: "Turn a charitable or community-serving idea into a small working Hasanat web app. Use when someone asks to build on Hasanat, clone the Hasanat starter, shape an idea into a first release, run it locally, add shared auth or Cloudflare D1, prepare Arabic/English RTL support, or submit a project to hasanat.dev."
---

# Hasanat Builder

Get the user from an idea to a visible local page before expanding scope. Keep the first run independent of cloud credentials, D1, OAuth, GitHub authentication, or deployment.

For a new project, begin by asking the user what they want to build. Do not require them to prepare a brief or customize a prompt first. Ask at most two short follow-up questions to identify the audience, problem, and first useful action, then continue with the workflow below.

## Operating principles

- Build for a clear public benefit. Ask what changes for the user, not only what features exist.
- Treat Arabic and English as first-class. Use logical CSS properties and test RTL when either language is in scope.
- Make the first release narrow enough to run locally in one session.
- Never request, print, or write secrets in chat. Ask the user to enter secrets directly in their terminal or local environment file.
- Do not overwrite an existing directory, discard local changes, initialize cloud resources, or deploy without confirmation.
- Use the repository's package manager from its lockfile. The official starter currently uses npm and `package-lock.json`.
- Verify each milestone with an executable check or browser view before moving on.

## Choose the path

- **Hasanat idea URL:** read the idea first. If the user is starting fresh, use **Start a project now** on the idea page so the platform creates a linked workspace and makes them lead. If they already have code, a repository, prototype, or live app, use **I already built something** so the standard submission is prefilled and linked to that idea. Never submit the same work as an unrelated standalone project.
- **New app:** follow the five-minute local start below.
- **Existing app:** inspect it, run its own checks, and preserve its framework. Add Hasanat integration only where useful.
- **No-code or design contribution:** shape the brief, prototype the core flow, and use the Builder Wiki instead of forcing a code workflow.
- **Join an existing project:** open `https://hasanat.dev/contribute`, choose a role and task, then work in that project's repository.

## Five-minute local start

### 1. Confirm the local target

Ask at most these two questions, and only when the answers are not already known:

- What problem should the first page solve, and for whom?
- What should someone be able to see or do in the first local version?

Turn the answer into one sentence:

> The first version helps **[audience]** do **[one action]** so they can **[benefit]**.

Defer accounts, dashboards, payments, admin tools, and production data unless one is the core action.

### 2. Check prerequisites

Resolve and run the bundled `scripts/check-environment.sh` from the installed skill directory:

```sh
sh <skill-directory>/scripts/check-environment.sh
```

If running before the skill has been installed into a workspace, check `git`, Node.js 20 or newer, and npm directly. Do not install system software without permission.

### 3. Create the project safely

Choose a short kebab-case folder name derived from the idea. Confirm it does not already exist, then run:

```sh
git clone --depth 1 https://github.com/hasanat-dev/starter.git <project-name>
cd <project-name>
npm install
cp .env.example .env
```

The HTTPS clone is public and does not require a GitHub account. Never delete an existing folder to make the command succeed.

### 4. Start before redesigning

Run the starter unchanged first:

```sh
npm run dev
```

Open the URL printed by the server, normally `http://localhost:4321`. Verify that the page renders and check the browser console. Do not continue until the user can see a working page locally.

### 5. Shape the first useful version

Inspect `AGENTS.md`, `README.md`, the page routes, and the existing design tokens. Implement only the agreed first outcome. Preserve the starter's established Astro, TypeScript, Tailwind, i18n, accessibility, and Cloudflare patterns.

Finish with:

```sh
npm run check
npm run build
```

Use browser verification at desktop and mobile sizes. Confirm Arabic reading order, alignment, and controls remain coherent in RTL.

## Add platform capabilities only when needed

- **Shared authentication:** read the starter's `.github/skills/hasanat-auth/SKILL.md` before changing auth code.
- **Cloudflare D1:** read `.github/skills/hasanat-d1/SKILL.md`. Ask before creating or migrating a database.
- **Hasanat design:** read `.github/skills/hasanat-design/SKILL.md`. Use real product content and assets; do not add emoji to the UI.
- **Deployment:** read `.github/skills/hasanat-deploy/SKILL.md`. Require a successful local build and explicit deployment approval.

## Prepare for Hasanat

Before submission, verify:

- The working experience communicates the public benefit.
- A real maintainer or lead is associated with the project.
- Arabic and English content, metadata, mobile layout, loading, empty, and error states are coherent.
- No secrets, personal data, generated build output, or local environment files are committed.
- `npm run check` and `npm run build` pass.
- Repository and live URLs are accurate.

Submit through `https://hasanat.dev/apps/submit` after signing in. Submission creates a pending project tied to the authenticated submitter; it does not publish automatically.

## Activate and operate the project

After the project workspace exists:

1. Confirm the accountable lead and make the project brief concrete.
2. Add at least one role-specific starter task. Use the workspace templates when they fit, and rewrite them when project context matters.
3. Add a shared working resource such as the repository, design file, or project board.
4. Post a structured weekly check-in covering what changed, blockers, the next step, and help needed.
5. Use the workspace readiness checklist before advancing from planning to building, beta, or launch. Do not bypass missing evidence by changing status directly.
6. Before launch, provide a live testable URL and gather real user feedback. Embed the Hasanat feedback widget and classify, prioritize, resolve, or reply to incoming feedback from the workspace.

When joining another project, use the application conversation to answer lead questions. If accepted with a first task, open that task immediately and post progress in the project workspace rather than moving coordination to private chat.

## Completion report

End with four concise facts:

1. Local URL and what is working.
2. Files or features changed.
3. Checks that passed.
4. The single next highest-value step.