Document AI-agent-ready project standard

AGENTIC_ARCHITECTURE.md

@@ -0,0 +1,37 @@
+# Agentic Architecture
+
+This document defines the architecture and collaboration model optimized for AI-agent interaction within the project.
+
+## Human + AI Collaboration Model
+The development lifecycle is a partnership:
+- **Humans**: Define the vision, approve architectural decisions, set safety gates, review pull requests, and manage production infrastructure.
+- **AI Agents**: Execute scoped tasks, audit repositories, write documentation, clean up technical debt, and implement isolated features based on approved plans.
+
+## Development-Time Agents
+Current AI integration focuses on development-time assistance:
+- Agents (Gemini, Claude) act as advanced coding partners.
+- They utilize the project standard layer (canonical memory, workflows) to orient themselves.
+- They operate in strict "Scoped PR lifecycle" modes, ensuring one task group equals one branch and one PR.
+
+## Future Product-Time Agents
+As the platform evolves, AI may be integrated into the runtime product:
+- E.g., an intelligent portfolio assistant that can answer questions about the documentation or the owner's experience.
+- Such agents will be isolated from core system state and will operate via controlled APIs or standard RAG patterns.
+
+## Agent Boundaries and Safety Gates
+To ensure safe operations, agents must respect the following boundaries:
+- **Production Code (`/app`, `/lib`)**: Requires verification of shared imports.
+- **Documentation (`/docs`)**: Lower risk, but requires local previews.
+- **Database (`/prisma`)**: Strict adherence to the `prisma migrate dev` workflow.
+- **Stop Gates**: Agents must halt and report if builds fail, tests fail, or they encounter ambiguity outside their scoped task.
+
+## Where AI May Integrate Later
+- **Documentation Intelligence**: Automated semantic search, tagging, and QA across Fumadocs.
+- **Agentic Workflow Dashboard**: A potential internal UI to monitor agent tasks, PRs, and lint debt.
+
+## What Must Remain Human-Approved
+Agents are strictly prohibited from independently modifying or executing:
+- Infrastructure and deployment configurations (`Dockerfile`, CI/CD workflows).
+- Authentication logic (`auth.ts`) and secret management.
+- Dependency changes (modifying `package.json` or `bun.lock`).
+- Production database migrations.

AGENTS.md

@@ -60,6 +60,12 @@ Strategic direction:
 - Keep repository policy in `AGENTS.md` and reusable procedures in `AGENT_WORKFLOWS.md`.
 - Do not create tool-specific skills, slash commands, hooks, MCP servers, or custom agents without explicit approval.
 
+### Project Standard & Planning Reference
+
+- Inspect `AI_PROJECT_STANDARD.md` for the overarching AI-ready standard.
+- Inspect `PRODUCT_VISION.md`, `AGENTIC_ARCHITECTURE.md`, and `ROADMAP.md` for product and technical direction.
+- Inspect `DECISION_LOG.md` for historical architectural decisions.
+
 ---
 
 ## Critical Rules

AI_PROJECT_STANDARD.md

@@ -0,0 +1,43 @@
+# AI-Agent-Ready Project Standard
+
+This document defines the standard layer for bootstrapping and maintaining an AI-agent-ready project. It outlines the required structure to ensure future AI coding agents can seamlessly interact with the repository, understand its boundaries, and follow safe contribution rules.
+
+## Core Structure
+Every future AI-ready project should include the following core files and folders:
+
+### Canonical Memory
+These files serve as the ground truth for repository policy and structure.
+- `AGENTS.md`: The canonical repository guidance and policy.
+- `PROJECT_STRUCTURE.md`: Defines the boundaries between production, learning, and local-only code.
+- `DECISION_LOG.md`: Lightweight ADRs (Architecture Decision Records) for logging significant technical choices.
+
+### Planning and Vision
+These files align agents and humans on the project's direction.
+- `PRODUCT_VISION.md`: Defines the product identity, target users, and AI integration principles.
+- `AGENTIC_ARCHITECTURE.md`: Outlines the human-AI collaboration model and technical architecture.
+- `ROADMAP.md`: Strategic timeline and future milestones.
+
+### Workflows
+These files define reusable procedures for agent tasks.
+- `AGENT_WORKFLOWS.md`: Portable procedures for recurring Git, PR, and repository work.
+- `prompts/agent-workflows/`: Reusable prompt templates (e.g., `status-and-next.md`).
+
+### Thin Tool Adapters
+These files provide tool-specific entry points without duplicating policy.
+- `CLAUDE.md`: For Claude Code.
+- `GEMINI.md`: For Gemini agents.
+- `.github/copilot-instructions.md`: For GitHub Copilot.
+
+## Bootstrap Guide
+To bootstrap this layer after running `bun create next-app`:
+1. Create the base canonical memory files (`AGENTS.md`, `PROJECT_STRUCTURE.md`).
+2. Create the planning and vision files to establish context.
+3. Establish the workflow procedures (`AGENT_WORKFLOWS.md`).
+4. Add thin tool adapters that instruct agents to read the canonical memory first.
+5. Ensure package manager policies (e.g., Bun as canonical) and linting/formatting rules are strictly defined in `AGENTS.md`.
+
+## Anti-Patterns (What Not To Do)
+- **Context Bloat**: Do not include massive logs, unstructured scratchpads, or redundant data in the standard layer.
+- **Duplicate Instructions**: Do not copy rules from `AGENTS.md` into tool-specific adapters (`GEMINI.md`, `CLAUDE.md`). Adapters must remain thin.
+- **Tool Lock-in**: Do not create tool-specific skills, slash commands, or MCP servers unless a repeated need is proven and explicitly approved.
+- **Uncontrolled Autonomy**: Do not allow agents to execute unstructured or unsafe commands. All tasks must follow the defined `AGENT_WORKFLOWS.md` procedures and respect boundaries.

DECISION_LOG.md

@@ -0,0 +1,33 @@
+# Decision Log
+
+This document records significant architectural and workflow decisions for the project.
+
+## Initial Decisions
+
+### 1. Bun is Canonical
+- **Decision**: Use Bun as the sole package manager and script runner.
+- **Rationale**: Speed, built-in tooling, and a single lockfile (`bun.lock`). npm is restricted unless required for bootstrapping.
+
+### 2. AGENTS.md is Canonical Policy
+- **Decision**: All repository policy, boundaries, and rules live in `AGENTS.md`.
+- **Rationale**: Prevents scattered instructions and ensures a single source of truth for all AI agents.
+
+### 3. PROJECT_STRUCTURE.md Defines Boundaries
+- **Decision**: Explicitly map production, documentation, and sandbox areas.
+- **Rationale**: Prevents agents from confusing learning code (`/src`) with production code (`/app`).
+
+### 4. AGENT_WORKFLOWS.md Defines Procedures
+- **Decision**: Reusable Git, PR, and validation procedures are standardized.
+- **Rationale**: Ensures predictable, safe agent behavior and prevents uncontrolled autonomy.
+
+### 5. Tool Adapters Stay Thin
+- **Decision**: Files like `GEMINI.md` and `CLAUDE.md` must only point to `AGENTS.md`.
+- **Rationale**: Avoids context bloat and out-of-sync policies across different AI platforms.
+
+### 6. No Premature AI Tooling
+- **Decision**: Do not build custom skills, slash commands, or MCP servers until a repeated need is proven.
+- **Rationale**: Prevents tool lock-in and maintenance overhead for unused features.
+
+### 7. Scoped PR Lifecycle
+- **Decision**: One task group = one branch = one PR.
+- **Rationale**: Ensures atomic, easily reviewable changes and minimizes regression risks.

GEMINI.md

@@ -0,0 +1,7 @@
+# Gemini Adapter
+
+- Read `AGENTS.md`, `PROJECT_STRUCTURE.md`, and `AGENT_WORKFLOWS.md` first.
+- Use `AI_PROJECT_STANDARD.md` for the future-facing AI-ready project setup.
+- Use `PRODUCT_VISION.md`, `AGENTIC_ARCHITECTURE.md`, `ROADMAP.md`, and `DECISION_LOG.md` for product and architecture direction.
+- Keep repository policy in `AGENTS.md`.
+- Do not duplicate full policy in `GEMINI.md`.

PRODUCT_VISION.md

@@ -0,0 +1,28 @@
+# Product Vision
+
+## Product Identity
+`taichi112.works` is evolving from a standard personal portfolio and documentation site into a robust, AI-agent-integrated software platform. It serves as both a public-facing portfolio and an internal playground for advanced AI agent workflows.
+
+## Target Users
+- **Public Users**: Developers, recruiters, and peers exploring technical documentation, design patterns, and professional experience.
+- **Internal Users (Human)**: The repository owner orchestrating development, managing AI agents, and deploying infrastructure.
+- **Internal Users (AI Agents)**: Coding agents (Gemini, Claude, Copilot) operating within defined boundaries to write, test, and document code.
+
+## Current Product Surface
+- Next.js App Router for portfolio pages and UI.
+- Fumadocs-based technical documentation in `/docs`.
+- Authentication and database-backed functionality (NextAuth, Prisma, PostgreSQL).
+- Software engineering and design-pattern learning artifacts in `/src` and `/demo`.
+
+## Future Direction
+The project will transition into a platform that actively uses AI to accelerate development, manage documentation, and eventually provide productized AI features to end-users. The goal is to build a maintainable platform where human and AI collaboration is seamless and safe.
+
+## AI Integration Principles
+- **Safety First**: AI agents must operate within strict repository boundaries and require human approval for high-risk changes (auth, infra, database).
+- **Single Source of Truth**: AI agents must rely on canonical memory (`AGENTS.md`) rather than inferred or disjointed instructions.
+- **Incremental Value**: AI integration should focus on solving immediate workflow bottlenecks (e.g., linting, docs) before attempting complex autonomous product features.
+
+## Non-Goals
+- Building an autonomous, completely human-free development cycle.
+- Over-engineering custom AI tools (skills, hooks) before establishing a clear, repeated need.
+- Migrating away from the core Next.js/Bun stack purely for AI experimentation.

ROADMAP.md

@@ -0,0 +1,28 @@
+# Roadmap
+
+This roadmap outlines the strategic phases for evolving the project from a prototype into a mature AI-agent-integrated platform.
+
+## Phase 1: Foundation and Safety
+- Establish the AI-agent-ready project standard layer (canonical memory, thin adapters).
+- Define strict repository boundaries and PR lifecycles.
+- Lock down the package manager (Bun) and deployment workflows.
+
+## Phase 2: Repository Quality and Lint Debt
+- Utilize AI agents for batch cleanup of existing lint and type debt.
+- Standardize the design-pattern learning sandboxes (`/src`, `/demo`).
+- Ensure robust automated validation for CI pipelines.
+
+## Phase 3: Documentation Intelligence
+- Leverage AI to audit, structure, and enhance Fumadocs content.
+- Introduce advanced MDX integrations and semantic linking.
+
+## Phase 4: Portfolio Assistant
+- Begin integrating product-time AI features.
+- Develop an intelligent assistant to navigate the portfolio and technical documentation.
+
+## Phase 5: Agentic Workflow Dashboard
+- Build internal tooling to visualize AI agent activity, monitor debt, and manage scoped PRs.
+
+## Phase 6: Productized AI Features
+- Expand the platform with user-facing AI tools or integrations based on learning artifacts.
+- Explore advanced AI use cases beyond development-time assistance.

prompts/agent-workflows/status-and-next.md

@@ -0,0 +1,32 @@
+# Workflow: Status and Next
+
+**Goal**:
+Understand the repository state, guidance, boundaries, and workflow rules, and recommend the next safest task.
+
+**Mode**:
+Audit-only.
+
+**Rules**:
+* Read the following files first:
+  - `AGENTS.md`
+  - `PROJECT_STRUCTURE.md`
+  - `AGENT_WORKFLOWS.md`
+  - `AI_PROJECT_STANDARD.md`
+  - `PRODUCT_VISION.md`
+  - `AGENTIC_ARCHITECTURE.md`
+  - `ROADMAP.md`
+  - `DECISION_LOG.md`
+* Do not modify files.
+* Do not stage anything.
+* Do not commit anything.
+* Do not push.
+* Do not create branches.
+* Do not install dependencies or run modifying commands.
+
+**Steps**:
+1. Run `git status --short` and `git branch --show-current`.
+2. Inspect the specified guidance and planning files.
+3. Summarize the current repository state and boundaries.
+4. Propose the next 3 tasks, ordered by safety and value, based on current repository state, repository boundaries, workflow rules, product vision, roadmap priorities, and known debt or risks.
+
+Stop after reporting. Do not modify files.