rbin-task-flow 1.5.0 → 1.7.0

package/.cursor/rules/coding_standards.mdc

@@ -21,12 +21,42 @@ src/
 └── shared/       # Global reusable code
 ```
 
+### Allowed folders in shared/ and features/ (Front web & Mobile only)
+
+In **front web** (Next.js, React, or other React-based web) or **mobile** (Expo, React Native) projects, only the following folder names may exist directly under `shared/` or under each feature in `features/`:
+
+| Folder        | Use                    |
+|---------------|------------------------|
+| `pages/`      | Web only — page components |
+| `screens/`    | Mobile only — screen components |
+| `components/` | UI components          |
+| `constants/`  | Constants              |
+| `utils/`      | Utilities              |
+| `validations/` | Validation helpers (e.g. `.validation.ts` for Zod) |
+| `hooks/`      | Custom hooks           |
+| `providers/`  | Context providers      |
+| `styles/`     | Styles                 |
+| `types/`      | TypeScript types       |
+| `libs/`       | Library wrappers       |
+| `services/`   | React Query / API wrappers |
+| `use-cases/`  | Pure API / business logic |
+| `schemas/`    | Zod (or similar) schemas |
+
+**No other folder names** are allowed under `shared/` or under `features/[feature-name]/`. Use only `pages/` for web and `screens/` for mobile; do not mix both in the same project type.
+
+### No subfolders in shared/ (Front web & Mobile only)
+
+In **front web** (Next.js, React) or **mobile** (Expo, React Native) projects, each folder under `shared/` must be **flat**: no subfolders. Files assume the responsibility through clear naming.
+
+- **shared/components/**: One file per component, directly in `shared/components/`. No nested folders (e.g. no `form/`, `inputs/`). Name files so the purpose is clear (e.g. `button.tsx`, `input-text.tsx`, `input-container.tsx`, `input-error.tsx`, `input-label.tsx`).
+- **shared/hooks/**, **shared/utils/**, **shared/validations/**, **shared/constants/**, etc.: Same rule — only files, no subfolders. Use the file name to carry the responsibility. Validation helpers (e.g. `required-email.validation.ts`) live in `shared/validations/`.
+
 ---
 
 ## Tech Stack
 
-### Front-end (Next.js)
-- **Framework**: Next.js 15+ with App Router
+### Front-end (Next.js / React)
+- **Framework**: Next.js 15+ with App Router, or React (Vite, CRA, or similar). These rules apply to any React-based web project.
 - **Language**: TypeScript (strict mode)
 - **Styling**: Tailwind CSS v4 + `clsx` + `tailwind-merge` via `cn()` helper
 - **UI Components**: shadcn/ui + `lucide-react` icons
@@ -37,7 +67,7 @@ src/
 - **E2E Testing**: Playwright and/or Cypress
 
 ### Mobile (Expo / React Native)
-- **Framework**: Expo with Expo Router
+- **Framework**: Expo with Expo Router, or React Native (bare or managed). These rules apply to both Expo and React Native.
 - **Language**: TypeScript (strict mode)
 - **Styling**: NativeWind + `clsx` + `tailwind-merge` via `cn()` helper
 - **Data Fetching**: `@tanstack/react-query`
@@ -61,7 +91,7 @@ src/
 
 The `app/` directory contains ONLY route definitions. Each file is a thin wrapper that imports and renders the feature page/screen.
 
-**Front-end (Next.js App Router):**
+**Front-end (Next.js App Router or React):**
 ```typescript
 // src/app/(private)/dashboard/page.tsx
 import { DashboardPage } from '@/features/dashboard/pages/dashboard.page'
@@ -71,7 +101,7 @@ export default function Dashboard() {
 }
 ```
 
-**Mobile (Expo Router):**
+**Mobile (Expo Router or React Native):**
 ```typescript
 // src/app/(private)/dashboard.tsx
 import { DashboardScreen } from '@/features/dashboard/screens/dashboard.screen'
@@ -283,6 +313,8 @@ export function DashboardActiveCard({ data, isLoading, isError }: DashboardActiv
 
 ## shared/ — Global Reusable Code
 
+In front web (Next.js, React) and mobile (Expo, React Native), `shared/` is flat per folder (no subfolders). One file per concern; naming carries the responsibility.
+
 ```
 shared/
 ├── components/
@@ -291,14 +323,11 @@ shared/
 │   ├── data-handler.tsx
 │   ├── skeleton.tsx
 │   ├── dialog.tsx
-│   └── form/
-│       └── inputs/
-│           ├── input-text.tsx
-│           ├── input-select.tsx
-│           └── shared/
-│               ├── input-container.tsx
-│               ├── input-error.tsx
-│               └── input-label.tsx
+│   ├── input-text.tsx
+│   ├── input-select.tsx
+│   ├── input-container.tsx
+│   ├── input-error.tsx
+│   └── input-label.tsx
 ├── hooks/
 │   ├── dialog.hook.tsx
 │   └── drawer.hook.tsx
@@ -312,11 +341,11 @@ shared/
 │   └── shared.ui.type.ts
 ├── constants/
 │   └── server-routes.constants.ts
+├── validations/
+│   ├── required-email.validation.ts
+│   ├── required-string.validation.ts
+│   └── required-phone.validation.ts
 └── utils/
-    ├── validation/
-    │   ├── required-email.validation.ts
-    │   ├── required-string.validation.ts
-    │   └── required-phone.validation.ts
     └── error.util.ts
 ```
 
@@ -516,8 +545,8 @@ export type ServiceInput<TData = unknown> = {
 ```typescript
 // src/features/auth/schemas/login.schema.ts
 import { z } from 'zod'
-import { requiredEmail } from '@/shared/utils/validation/required-email.validation'
-import { requiredString } from '@/shared/utils/validation/required-string.validation'
+import { requiredEmail } from '@/shared/validations/required-email.validation'
+import { requiredString } from '@/shared/validations/required-string.validation'
 
 export const loginSchema = z.object({
   email: requiredEmail(),
@@ -529,7 +558,7 @@ export type LoginSchema = z.infer<typeof loginSchema>
 
 **Reusable validators in shared/:**
 ```typescript
-// src/shared/utils/validation/required-string.validation.ts
+// src/shared/validations/required-string.validation.ts
 import { z } from 'zod'
 
 export const requiredString = ({ field, min = 1 }: { field: string; min?: number }) =>
@@ -547,7 +576,7 @@ import { zodResolver } from '@hookform/resolvers/zod'
 import { useForm } from 'react-hook-form'
 import { LoginSchema, loginSchema } from '@/features/auth/schemas/login.schema'
 import { SessionCreateService } from '@/features/auth/services/session-create.service'
-import { InputText } from '@/shared/components/form/inputs/input-text'
+import { InputText } from '@/shared/components/input-text'
 import { Button } from '@/shared/components/button'
 
 export function LoginForm() {
@@ -572,7 +601,7 @@ export function LoginForm() {
 
 **Input uses `Controller` from RHF and is generic:**
 ```typescript
-// src/shared/components/form/inputs/input-text.tsx
+// src/shared/components/input-text.tsx
 import { Control, Controller, FieldValues, Path, PathValue } from 'react-hook-form'
 import { cn } from '@/shared/libs/tw-merge'
 
@@ -616,13 +645,24 @@ export function InputText<T extends FieldValues>({
 
 ## File Naming Conventions
 
-Use kebab-case for all filenames. Suffix reflects the file's role:
+### Rule for front (web & mobile): outside `app/` only
+
+Every file outside the `app/` folder must follow:
+
+- **Format**: lowercase, words separated by `-`, then `.tipo.ext` (suffix by role).
+- **Examples**: `pagina-exemplo.page.tsx`, `login.schema.ts`, `session-create.use-case.ts`, `dashboard-active.type.ts`.
+
+**Components are the exception**: do **not** use a `.component` suffix. Use only kebab-case + extension, e.g. `pagina-exemplo.tsx`, `dashboard-revenue-card.tsx`, `input-text.tsx`.
+
+**Another exception**: files inside any `styles/` folder do not need to follow this pattern (e.g. CSS/SCSS modules may use their own convention).
+
+### Suffix by role
 
 | Role | Suffix | Example |
 |------|--------|---------|
-| Page component | `.page.tsx` | `dashboard.page.tsx` |
+| Page component | `.page.tsx` | `pagina-exemplo.page.tsx` |
 | Screen component (mobile) | `.screen.tsx` | `login.screen.tsx` |
-| UI component | `.tsx` | `dashboard-revenue-card.tsx` |
+| UI component | (no suffix) `.tsx` | `dashboard-revenue-card.tsx`, `input-text.tsx` |
 | React Query service | `.service.tsx` | `session-create.service.tsx` |
 | API call (pure) | `.use-case.ts` | `session-create.use-case.ts` |
 | Zod schema | `.schema.ts` | `login.schema.ts` |
@@ -630,7 +670,7 @@ Use kebab-case for all filenames. Suffix reflects the file's role:
 | API response type | `.api.type.ts` | `session.api.type.ts` |
 | Domain type | `.type.ts` | `dashboard-active.type.ts` |
 | Utility | `.util.ts` | `error.util.ts` |
-| Validation helper | `.validation.ts` | `required-email.validation.ts` |
+| Validation helper | `.validation.ts` | `required-email.validation.ts` (in `validations/`) |
 | Constants | `.constants.ts` | `server-routes.constants.ts` |
 
 ---
@@ -684,7 +724,7 @@ export const useAuth = () => useContext(AuthContext)
 
 ## Testing
 
-### Front-end (Next.js)
+### Front-end (Next.js / React)
 - **E2E**: Playwright and/or Cypress
 - Tests live in `e2e/` or `cypress/` at project root
 - Test files: `[feature].spec.ts` (Playwright) or `[feature].cy.ts` (Cypress)
@@ -710,3 +750,4 @@ export const useAuth = () => useContext(AuthContext)
 8. **Type everything**: No `any`. All props, params, and return values must be typed.
 9. **Shared is truly shared**: Only put in `shared/` what is used by 2+ features.
 10. **Naming reflects role**: File name + suffix must make the file's purpose immediately obvious.
+11. **No barrel files for re-exports**: Do not use `index.ts` (or `index.tsx`) only to re-export other modules. Import directly from the source file (e.g. `from '@/shared/components/button'` not `from '@/shared/components'`). An `index.ts` is only allowed when it contains real logic or composition, not mere re-exports.

package/AGENTS.md

@@ -0,0 +1,42 @@
+# Project norms (Codex)
+
+This repo follows the same development norms as in `.cursor/rules/` and `CLAUDE.md`. When working here, follow these rules.
+
+## Git
+
+- **Never run** `git add`, `git commit`, `git push`, `git pull`, `git merge`, `git checkout`, `git reset`, `git rebase`, etc.
+- **Only suggest** git commands; the user runs them.
+- You **may** run read-only git: `git status`, `git diff`, `git log`, `git show`, `git branch` (list only).
+
+## Commits
+
+- After completing tasks, **suggest** a commit message (Conventional Commits: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`).
+- Include task/subtask ID when relevant, e.g. `Task ID: 3.2`.
+
+## Code and comments
+
+- **No explanatory comments** in code; keep code self-explanatory via names.
+- **Document non-obvious or complex topics** in `dev-logs/` (markdown).
+- **Allowed comments**: only section separators in this form:
+  ```text
+  // ────────────────────────────────
+  // Section Name
+  // ────────────────────────────────
+  ```
+
+## RBIN Task Flow
+
+- **Task flow** always means **RBIN Task Flow**.
+- Tasks: `.task-flow/tasks.input.txt` (format: `- Task description`).
+- Status: `.task-flow/tasks.status.md` and `.task-flow/.internal/status.json`.
+- **Commands** to support: `task-flow: sync`, `task-flow: think`, `task-flow: audit`, `task-flow: status`, `task-flow: run next X`, `task-flow: run X` (or `X,Y` / `all`), `task-flow: review X`, `task-flow: refactor X`, `task-flow: estimate X`, `task-flow: report X`.
+- When running `task-flow: audit`: scan the codebase, score it against `.cursor/rules/coding_standards.mdc`, present a report, and ask the user which improvements to adopt — never impose changes.
+- When running subtasks: read `.task-flow/.internal/tasks.json` and `status.json`, implement, then update `status.json` and `tasks.status.md` (mark done, refresh summary).
+- Use context from `.task-flow/contexts/` when subtask instructions reference it.
+
+## Full rules
+
+For complete wording and examples, see:
+
+- `CLAUDE.md` – overview and task-flow commands
+- `.cursor/rules/` – all rules (git, commits, comments, task-flow, etc.)

package/lib/install.js

@@ -48,7 +48,7 @@ async function installInProject(targetPath, options = {}) {
 
     spinner.text = 'Copying configuration files...';
 
-    await copyConfigs(targetPath);
+    await copyConfigs(targetPath, isUpdate);
 
     spinner.text = 'Updating .gitignore...';
 
@@ -69,14 +69,14 @@ async function installInProject(targetPath, options = {}) {
   }
 }
 
-async function copyConfigs(targetPath) {
+async function copyConfigs(targetPath, isUpdate = false) {
   const cursorRulesPath = path.join(TEMPLATE_DIR, '.cursor/rules');
+  const cursorRulesDest = path.join(targetPath, '.cursor/rules');
   if (fs.existsSync(cursorRulesPath)) {
-    await fs.copy(
-      cursorRulesPath,
-      path.join(targetPath, '.cursor/rules'),
-      { overwrite: true }
-    );
+    if (isUpdate && fs.existsSync(cursorRulesDest)) {
+      await fs.emptyDir(cursorRulesDest);
+    }
+    await fs.copy(cursorRulesPath, cursorRulesDest, { overwrite: true });
     showSuccess('Cursor rules');
   }
 
@@ -110,6 +110,16 @@ async function copyConfigs(targetPath) {
     showSuccess('Claude instructions');
   }
 
+  const agentsPath = path.join(TEMPLATE_DIR, 'AGENTS.md');
+  if (fs.existsSync(agentsPath)) {
+    await fs.copy(
+      agentsPath,
+      path.join(targetPath, 'AGENTS.md'),
+      { overwrite: true }
+    );
+    showSuccess('Codex instructions (AGENTS.md)');
+  }
+
   await copyTaskFlow(targetPath);
 }
 
@@ -119,39 +129,22 @@ async function copyTaskFlow(targetPath) {
 
   await fs.ensureDir(taskFlowDest);
 
-  showSuccess('Task Flow directory');
-  showInfo('Note: .internal/tasks.json and .internal/status.json are NOT overwritten (your data is safe)');
-
-  const contextsDest = path.join(taskFlowDest, 'contexts');
-  await fs.ensureDir(contextsDest);
-  showSuccess('Contexts directory (.task-flow/contexts/)');
-
-  const docsDest = path.join(taskFlowDest, 'docs');
-  await fs.ensureDir(docsDest);
-  showSuccess('Documentation directory (.task-flow/docs/)');
-
-  const exampleSrc = path.join(taskFlowSrc, 'contexts/example.png.txt');
-  const exampleDest = path.join(contextsDest, 'example.png.txt');
-  if (fs.existsSync(exampleSrc) && !fs.existsSync(exampleDest)) {
-    await fs.copy(exampleSrc, exampleDest);
-  }
-
-  const files = [
-    { name: 'README.md', overwrite: true },
-    { name: 'tasks.input.txt', overwrite: false },
-    { name: 'tasks.status.md', overwrite: false }
+  const PROTECTED = [
+    path.join(taskFlowDest, '.internal'),
   ];
 
-  for (const file of files) {
-    const src = path.join(taskFlowSrc, file.name);
-    const dest = path.join(taskFlowDest, file.name);
+  await fs.copy(taskFlowSrc, taskFlowDest, {
+    overwrite: true,
+    filter: (src) => {
+      return !PROTECTED.some((p) => src.startsWith(p));
+    },
+  });
 
-    if (fs.existsSync(src)) {
-      if (file.overwrite || !fs.existsSync(dest)) {
-        await fs.copy(src, dest, { overwrite: file.overwrite });
-      }
-    }
-  }
+  await fs.ensureDir(path.join(taskFlowDest, 'contexts'));
+  await fs.ensureDir(path.join(taskFlowDest, 'docs'));
+
+  showSuccess('Task Flow directory (overwritten)');
+  showInfo('Protected: .internal/ (your task data is safe)');
 }
 
 async function updateGitignore(targetPath) {
@@ -167,7 +160,8 @@ async function updateGitignore(targetPath) {
     '.claude/',
     '.cursor/',
     '.task-flow/',
-    'CLAUDE.md'
+    'CLAUDE.md',
+    'AGENTS.md'
   ];
 
   for (const entry of entries) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rbin-task-flow",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "AI-powered task management for Claude and Cursor",
   "main": "index.js",
   "bin": {
@@ -33,6 +33,7 @@
     ".task-flow/",
     ".model-versions.json",
     "CLAUDE.md",
+    "AGENTS.md",
     "lib/"
   ],
   "preferGlobal": true,