AGENT SKILL

scaffold-project

Centralized full-stack project scaffold — bootstraps a complete Python/FastAPI backend skeleton (bootstrap) and scaffolds Next.js (web/) or React Chrome Extension (extension/) frontends (setui) with 11 themes and AI design system intelligence.

License 许可
MIT
最近更新
2026-11-11
Stars
★ 3
Forks
0

01 前言 Front Matter

name
scaffold-project
description
Centralized full-stack project scaffold — bootstraps a complete Python/FastAPI backend skeleton (bootstrap) and scaffolds Next.js (web/) or React Chrome Extension (extension/) frontends (setui) with 11 themes and AI design system intelligence.

02 资源文件 135

03 SKILL.md 正文

Scaffold Project

"One command. Full-stack production architecture."

Initializes a complete, production-ready full-stack application from scratch:

  1. Backend (bootstrap tool): FastAPI entrypoint, configuration layer, helpers, SQLite/SQLAlchemy database layer, auth system with scoped JWTs, intelligent agent lifecycle & validators, and standard agent rules.
  2. Frontend (setui tool): Complete Next.js + Tailwind + shadcn/ui frontend (web/) or React + Vite Chrome Extension (extension/) with 11 built-in themes and AI design system generation via ui-ux-pro-max.

How to Use

1. Scaffold Backend Skeleton (bootstrap)

Initializes the complete backend architecture into an empty project directory:

human-skills '{
    "tool_name": "bootstrap",
    "tool_args": {
        "destination": "/path/to/new_project"
    }
}'

Or via direct curl (no dependencies):

curl -sSL https://raw.githubusercontent.com/mdnaimul22/human-skills/main/skills/storage/my_skills/scaffold-project/resources/initialize/backend/bootstrap.py | python3

2. Scaffold Frontend Client (setui)

Scaffold a Next.js web application (web/) or React Chrome Extension (extension/) inside the project root:

# Basic Next.js frontend (web/)
human-skills '{
    "tool_name": "setui",
    "tool_args": {
        "destination": "/path/to/new_project"
    }
}'

# With AI Design System generation (ui-ux-pro-max)
human-skills '{
    "tool_name": "setui",
    "tool_args": {
        "destination": "/path/to/new_project",
        "action": "frontend",
        "design_query": "beauty spa wellness premium",
        "density": 5,
        "motion": 6
    }
}'

# React + Vite Chrome Extension (extension/)
human-skills '{
    "tool_name": "setui",
    "tool_args": {
        "destination": "/path/to/new_project",
        "action": "chrome-extension",
        "design_query": "developer productivity dashboard"
    }
}'

Full-Stack Project Structure

When both backend and frontend are scaffolded:

project_root/
├── main.py                  ← FastAPI entry point with auto-kill, health check, lifespan
├── .env                     ← Environment variables (fill from .env.example)
├── .env.example             ← Template for required env vars
├── .models.example          ← Template for AI model providers
├── .gitignore               ← Pre-configured for Python, Node, and secrets
├── README.md
├── LICENSE                  ← MIT License
├── docs/                    ← Documentation & generated brand guidelines
├── logs/                    ← Layer-based rotating logs
├── deploy/nginx/            ← Production Nginx configuration templates
│
├── .agents/rules/           ← Permanent coding standards synced from human-skills
│   ├── coding-standards.md
│   ├── architecture-patterns.md
│   ├── maintenance-testing.md
│   ├── config-path-rules.md
│   ├── config-usage-rules.md
│   ├── helpers-usage-rules.md
│   ├── project-config-example.md
│   ├── project-tree-example.md
│   └── common-git-workflow.md
│
├── src/                     ← Backend application core
│   ├── config/              ← Settings, env, sandboxed file I/O, hierarchical dual logger
│   ├── db/                  ← SQLAlchemy async engine, OwnershipMixin, models, repositories
│   ├── helpers/             ← Rate limiting, exceptions, date utils, port kill switch, tailscale
│   ├── core/                ← Business logic, password hashing, scoped JWTs, intelligent agents
│   │   ├── agents/          ← BaseAgent, AgentFactory, GeneralAgent lifecycle
│   │   └── validators/      ← Domain invariant pipeline
│   ├── providers/           ← External integrations (Email, Google OAuth, LLM rotator, proxy)
│   ├── schema/              ← Pydantic contracts (auth, common envelopes, agent protocols)
│   ├── services/            ← Fan-in use-case orchestration (AuthService, AgentService)
│   └── routers/             ← HTTP endpoints & auth dependencies (/api/auth, /api/agent)
│
├── tests/                   ← Modular test suite (128 passing tests out-of-the-box)
│   ├── core/
│   ├── routers/
│   ├── services/
│   └── helpers/
│
└── web/                     ← Next.js frontend (scaffolded via setui)
    ├── src/
    │   ├── app/             ← App router (layout, globals.css with 11 themes, auth pages)
    │   ├── components/      ← shadcn/ui components (30+ auto-installed), layout, navbar, sidebar
    │   ├── lib/             ← Type-safe FastAPI client (api.ts with JWT Bearer & 422 parsing)
    │   └── hooks/           ← State management (use-sidebar, use-auth with Zustand persist)
    ├── components.json
    ├── tailwind.config.ts
    └── package.json

Built-in Auth System

The scaffold ships with a production-grade authentication system out of the box:

Auth Endpoints

Method Endpoint Auth Purpose
POST /api/auth/register ❌ Email signup → sends verification email
GET /api/auth/verify-email ❌ Verify email via token in query
POST /api/auth/login ❌ Email/password login → access + refresh tokens
POST /api/auth/google ❌ Google OAuth login/signup
POST /api/auth/refresh ❌ Rotate access + refresh tokens
POST /api/auth/forgot-password ❌ Request password reset email
POST /api/auth/reset-password ❌ Reset password with token
POST /api/auth/change-password ✅ Change password (authenticated)
GET /api/auth/me ✅ Get current user profile
PATCH /api/auth/me ✅ Update profile (name)
POST /api/auth/logout ✅ Client-side token clear guidance

Scoped JWT Tokens

Purpose Expiry Usage
access 15 minutes API Authorization header (Bearer <token>)
refresh 7 days POST /api/auth/refresh only
verify_email 24 hours Email verification link
reset_password 1 hour Password reset link

User ↔ Service Data Ownership

Use OwnershipMixin for any model that belongs to a user:

from src.db import Base, TimestampMixin, OwnershipMixin

class Post(Base, TimestampMixin, OwnershipMixin):
    __tablename__ = "posts"
    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_uuid)
    title: Mapped[str] = mapped_column(String(200), nullable=False)

BaseRepository provides list_by_owner(user_id) and count_by_owner(user_id) for scoped queries to prevent IDOR attacks.


Intelligent Agent Architecture

The scaffold includes a production agent framework in src/core/agents:

  • BaseAgent: Abstract base with streaming, retry, and execution lifecycle.
  • AgentFactory: Configuration-driven agent instantiation.
  • Domain Validators: Invariant validation pipeline in src/core/validators.
  • Agent Router: HTTP interface at /api/agent/run with authentication guards.

Frontend Architecture (setui)

  • 11 Curated Themes: Default, Dark, Slate, Neon, Ocean, Cyberpunk, Velvet, Sunset, Forest, Luxury, Custom AI.
  • shadcn/ui Suite: 30+ pre-configured UI primitives with zero manual initialization needed.
  • FastAPI Client (src/lib/api.ts): Built-in JWT Bearer header injection, timeout protection, and Pydantic 422 error unpacking.
  • Design Intelligence: Passing design_query auto-generates brand guidelines (docs/brand-guidelines.md), design tokens (design-tokens.json), and typography pairings.

For comprehensive UI details, see [scaffold-ui.md](file:///home/naimul/human-skills/skills/storage/my_skills/scaffold-project/resources/scaffold-ui.md).


Post-Bootstrap Checklist

  • [ ] Copy .env.example → .env and fill mandatory fields
  • [ ] Set JWT_SECRET to a strong random value for production
  • [ ] Configure SMTP settings for email verification/password reset
  • [ ] (Optional) Set GOOGLE_CLIENT_ID for Google OAuth
  • [ ] Run backend: python3 main.py (auto-kills orphaned processes on port 8000)
  • [ ] Run frontend: cd web && npm run dev (connects to backend at http://localhost:8000)

04 同仓库更多 Skills

mdnaimul22
mdnaimul22/human-skills

system-lifecycle-designer

Universal architectural methodology for designing granular, atomic, and sub-atomic lifecycles and end-to-end workflows for single functionality integrations across any domain (daemons, batch jobs, request transactions, resource pools). Provides patterns for deterministic identity, pre-commit validation, differential reconciliation, sticky leasing, state machines, transactional persistence, and closed-loop feedback.

★ 3
mdnaimul22
mdnaimul22/human-skills

style-sampling

Make a new episode in a proven video style - Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime - on the person's topic. Use for "an episode of", "in the style of", "sample this style", 「用这个风格做一集」. One video to copy is reverse-any-video.

★ 3
mdnaimul22
mdnaimul22/human-skills

reverse-any-video

Rebuild any video file as an editable HyperFrames project - motion graphics, talking heads, live action or AI-generated footage - checked against the original frame by frame. Use to reverse, recreate, remake, replicate or copy a video, or 「复刻这个视频」「照着这个视频做一个」.

★ 3
mdnaimul22
mdnaimul22/human-skills

typescript-patterns

TypeScript patterns for strict, type-safe, maintainable code in modern TypeScript and JavaScript applications. Covers strict compiler configuration, type design, narrowing, discriminated unions, generics, async and error handling, module boundaries, dependency hygiene, and type-level testing. Use when writing or reviewing TypeScript or JavaScript code.

★ 3
mdnaimul22
mdnaimul22/human-skills

test-collaboration

Inventory and govern a project's test assets. Connect requirements, business rules, risks, bugs, and cross-boundary contracts to stable TEST-IDs and executable evidence in the repository's existing test registry or TESTS.md. Use for test inventory, test gap analysis, unit/integration/contract/E2E/smoke classification, bug-to-test regression protection, consumer/provider contract testing, test-necessity review, and pre-delivery evidence review.

★ 3
mdnaimul22
mdnaimul22/human-skills

story-lifecycle

Manage a file-based epic → story → sprint development loop without requiring an external project management tool. Creates and tracks epics, breaks them into user stories, assigns them to sprints, and drives implementation story by story. Use when starting a new feature initiative or when the team has no Jira/Linear/Taiga but needs structured delivery tracking.

★ 3