diff --git a/AGENTIC_ARCHITECTURE.md b/AGENTIC_ARCHITECTURE.md new file mode 100644 index 0000000..eb25f79 --- /dev/null +++ b/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. diff --git a/AGENTS.md b/AGENTS.md index ffcb4f1..bfb9699 100644 --- a/AGENTS.md +++ b/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 diff --git a/AI_PROJECT_STANDARD.md b/AI_PROJECT_STANDARD.md new file mode 100644 index 0000000..66d9160 --- /dev/null +++ b/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. diff --git a/DECISION_LOG.md b/DECISION_LOG.md new file mode 100644 index 0000000..dfdb96f --- /dev/null +++ b/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. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..3665859 --- /dev/null +++ b/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`. diff --git a/PRODUCT_VISION.md b/PRODUCT_VISION.md new file mode 100644 index 0000000..9a38102 --- /dev/null +++ b/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. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..c89f17d --- /dev/null +++ b/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. diff --git a/prompts/agent-workflows/status-and-next.md b/prompts/agent-workflows/status-and-next.md new file mode 100644 index 0000000..eee9dbc --- /dev/null +++ b/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.